用途:为 Go 项目编写与维护 OpenAPI/Swagger 文档,把注解注释当作 API 契约,让 Swagger UI 成为调用方的权威参考。提供构建(新项目或已有项目接入)与审计(检查注解完整性、正确性与安全覆盖)两种模式。
依赖与初始化:安装 swag:go install github.com/swaggo/swag/cmd/swag@latest。生成文档:swag init 生成 docs/ 下的 docs.go、swagger.json、swagger.yaml;若通用信息不在 main.go,用 swag init -g cmd/api/main.go;swag fmt 用于格式化注解注释。
接入方式:导入 docs 包注册规范,仅接 UI 时用空白导入 import _ "yourmodule/docs",需运行时覆盖 docs.SwaggerInfo 时用命名导入。按框架挂载 UI 端点,例如 Gin 用 r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)),Echo、Fiber、net/http、Chi 各有对应写法,访问 /swagger/index.html。多环境可用命名导入后覆盖 docs.SwaggerInfo.Host 与 BasePath。
注解能力:通用信息注解(@title、@version、@description、@host、@BasePath、@schemes、@contact、@license、@securityDefinitions 等)放在 main.go 或 -g 指定文件;操作注解(@Summary、@Description、@Tags、@Accept、@Produce、@Param、@Success、@Failure、@Router、@Security)标注在 handler 上,标准 godoc 注释需位于 swag 注解之前。@Param 支持 path、query、body、header、formData,并可加 default、minimum、maximum、minLength、maxLength、Enums、example、collectionFormat 等属性;@Success/@Failure 支持 {object}、{array}、基础类型,swag v2 支持泛型与嵌套组合。安全定义在 API 级声明,端点用 @Security 应用,支持 Bearer/JWT、API Key、Basic、OAuth2。结构体标签可补充 example、enums、swaggertype、swaggerignore、extensions。
常见限制与错误:缺少 docs 空白导入会导致 UI 为空;代码改动后未重新 swag init 会使文档过期;body 参数用基础类型会生成失败,需用命名结构体;受保护路由漏写 @Security 会缺少锁图标;通用信息注解放错文件会被静默跳过;map 类型需命名结构体或 swaggertype;含空格的 @Tags 需加引号。生产环境应保护 Swagger UI 端点;gRPC 场景应改用 grpc-gateway 的 OpenAPI 生成器。资料未提供收费、价格与平台信息。