openapi

Documentation

Index

• func DescribeRoute(handlerFn any, doc RouteDoc)
• func DescribeSchema(sch *openapi3.SchemaRef, description, example string) *openapi3.SchemaRef
• func RegisterCommentParser(fn CommentParser)
• func RegisterManualPath(path string, item *openapi3.PathItem)
• func RegisterMiddlewareDoc(fn any, h DocHook)
• func RegisterParamBinderSchema[T any](s *openapi3.Schema)
• func RegisterTypeSchema[T any](s *openapi3.Schema)
• func RegisterTypeSchemaFunc[T any](fn func() *openapi3.Schema)
• type CommentParser
• type DocHook
• type ErrorDecl
• type HeaderDecl
• type RouteDoc

Functions

func DescribeRoute

func DescribeRoute(handlerFn any, doc RouteDoc)

DescribeRoute 注册路由级纯文档增强。 handlerFn 传业务 handler 函数引用（如 handlers.GetUser），内部反射取名做 key； 在 Generate 之前调用（通常 main_doc.go 的 init()）。 同 key 重复注册 panic（防复制粘贴错）；注册后未匹配到任何路由的， Generate 结束时输出警告（注册不会静默失效）。

func DescribeSchema

func DescribeSchema(sch *openapi3.SchemaRef, description, example string) *openapi3.SchemaRef

DescribeSchema 给 schema 引用附加描述/示例（$ref 用 AllOf 包装）。 供自定义 CommentParser 实现；已有描述/示例时不覆盖。

func RegisterCommentParser

func RegisterCommentParser(fn CommentParser)

RegisterCommentParser 注册自定义字段注释解析器（全局唯一，重复注册 panic）。 src 为注释原文；sch 为字段当前 schema 引用（$ref 时 Value 为 nil，可用 DescribeSchema 包装）。 仅在 OptionWithSourceComments 开启后生效；未开启时 Generate 输出警告。

func RegisterManualPath

func RegisterManualPath(path string, item *openapi3.PathItem)

RegisterManualPath 补录非模板路由（混合项目里绕过统一模板的老接口）。 与模板路由同 path+method 冲突时 panic；item 会原样并入 Paths。

func RegisterMiddlewareDoc

func RegisterMiddlewareDoc(fn any, h DocHook)

RegisterMiddlewareDoc 把中间件函数与文档钩子绑定（可选择性注册）。 fn 传业务中间件函数引用（如 middleware.Auth），内部反射取名字做键， 调用方不需要手写名字字符串。

func RegisterParamBinderSchema

func RegisterParamBinderSchema[T any](s *openapi3.Schema)

RegisterParamBinderSchema 给自定义绑定类型声明文档 schema（缺省 string）。 例：CSV ID 列表 → array<integer>。注册放 main_doc.go，release 零影响。

func RegisterTypeSchema

func RegisterTypeSchema[T any](s *openapi3.Schema)

RegisterTypeSchema 注册类型级文档 schema 覆盖（组件替换）。 被覆盖的类型在 body/组件位置使用注册 schema（$ref 结构不变）； query/path 参数位置仍由 ParamBinder 语义优先（HTTP 形态是原始串）。 同类型重复注册覆盖；请勿在生成期修改注册的 schema（需要动态构建用 RegisterTypeSchemaFunc）。

func RegisterTypeSchemaFunc

func RegisterTypeSchemaFunc[T any](fn func() *openapi3.Schema)

RegisterTypeSchemaFunc 函数式类型覆盖：每次生成调用 fn 取新实例（避免共享可变状态）。

Types

type CommentParser

type CommentParser func(src string, sch *openapi3.SchemaRef) *openapi3.SchemaRef

CommentParser 字段/类型注释解析器。 src：注释原文（多行保留换行）； sch：当前 schema 引用——内联 schema 时 Value 非 nil 可直接改； 字段类型是命名结构体时为 $ref（Value 为 nil），可用 DescribeSchema 包装。 返回最终生效的引用。

type DocHook

type DocHook = func(op *openapi3.Operation)

DocHook 中间件文档钩子：生成 operation 时被调用，可修改任意字段 （security、header 参数、响应码等）。未注册钩子的中间件不进文档。

type ErrorDecl

type ErrorDecl struct {
	// Status HTTP 状态码（必填，<=0 时 DescribeRoute panic）
	Status int
	// Code 业务 code；0 → 跟随状态码（与运行时 resolveError 约定一致：
	// HTTP 200 → code=7，非 200 → code=status）
	Code int
	// Description 响应描述（如 "用户不存在"），同时作为响应体 msg 的示例值
	Description string
	// Schema 自定义覆盖：整体替换失败响应体（如自定义错误协议）；
	// 缺省由壳推导
	Schema *openapi3.SchemaRef
}

ErrorDecl 错误响应声明。

type HeaderDecl

type HeaderDecl struct {
	Name        string
	Description string
	Required    bool
	Schema      *openapi3.Schema // 缺省 string
}

HeaderDecl 成功响应头声明。

type RouteDoc

type RouteDoc struct {
	// OperationID 覆盖。空 → 裸函数名；裸名跨路由重复时生成警告提示注册
	OperationID string

	// Errors 声明该接口可能返回的错误响应（4xx/5xx）。
	// 响应体默认由路由实际生效的壳推导（OptionWithEnvelope / RouteMeta.Envelope / 默认壳），
	// 保证文档与运行时形态一致；Schema 可整体覆盖。
	Errors []ErrorDecl

	// ResponseHeaders 声明成功响应的自定义响应头
	// （运行时经 contract.Response[R].Headers 动态发出，静态推不出，只能声明）
	ResponseHeaders []HeaderDecl

	// Hide 从文档中剔除该接口（运行时照常服务）——内网接口的轻量方案
	Hide bool

	// Hook 兜底：拿到最终 operation 任意改写。
	// 应用顺序：中间件文档钩子先、本钩子最后。
	Hook DocHook
}

RouteDoc 路由级纯文档增强。