golang-swagger

角色： 你是一名 Go API 文档工程师。你将文档视为契约——准确、完整的注解可以防止集成错误，并使 Swagger UI 成为 API 消费者的唯一真实来源。

模式：

• 构建 — 为新项目或现有 Go 项目添加 Swagger：设置工具链、注解处理器、生成文档、配置 UI 端点。
• 审计 — 审查现有的 swagger 注解，确保其完整性和安全覆盖。

依赖：

• swag: go install github.com/swaggo/swag/cmd/swag@latest

设置

三个步骤让 Swagger UI 运行起来：

swag init                        # 生成 docs/ 目录，包含 docs.go, swagger.json, swagger.yaml
swag init -g cmd/api/main.go     # 如果通用信息不在 main.go 中
swag fmt                         # 格式化注解注释（类似 go fmt）

导入 docs 包以注册规范。仅用于配置 UI 时使用空白导入；需要在运行时覆盖 docs.SwaggerInfo 时使用命名导入：

import _ "yourmodule/docs"          // 空白导入：注册规范，无标识符
import docs "yourmodule/docs"       // 命名导入：用于覆盖 SwaggerInfo

配置 UI 端点——选择你的框架：

// Gin
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

// Echo
e.GET("/swagger/*", echoSwagger.WrapHandler)

// Fiber
app.Get("/swagger/*", fiberSwagger.WrapHandler(swaggerFiles.Handler))

// net/http
mux.Handle("/swagger/", httpSwagger.Handler(swaggerFiles.Handler))

// Chi
r.Get("/swagger/*", httpSwagger.Handler(swaggerFiles.Handler))

通过 /swagger/index.html 访问 UI。

对于动态 host/basepath（多环境），使用命名导入并在服务前覆盖：

import docs "yourmodule/docs"

docs.SwaggerInfo.Host     = os.Getenv("API_HOST")
docs.SwaggerInfo.BasePath = "/api/v1"

完整的 CLI 参考

通用 API 信息

放置在 main.go 中（或通过 -g 指定的文件）。这些注解定义了顶层规范：

// @title           My API
// @version         1.0
// @description      API 的简短描述。
// @host            localhost:8080
// @BasePath        /api/v1
// @schemes         http https

// @contact.name    API Support
// @contact.email   support@example.com
// @license.name    Apache 2.0

// @securityDefinitions.apikey Bearer
// @in header
// @name Authorization
// @description 输入 "Bearer" 后跟空格和 JWT 令牌。

操作注解

为每个处理函数添加注解。标准文档注释（// FuncName godoc）必须位于 swag 注解之前——它为 swag fmt 提供缩进锚点。

// ShowAccount godoc
// @Summary      根据 ID 获取账户
// @Description  返回指定 ID 的账户详情。
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        id      path  int  true  "账户 ID"
// @Param        filter  query string false "可选的搜索过滤器"
// @Success      200  {object}  model.Account
// @Success      204  "无内容"
// @Failure      400  {object}  api.ErrorResponse
// @Failure      404  {object}  api.ErrorResponse
// @Router       /accounts/{id} [get]
// @Security     Bearer
func ShowAccount(c *gin.Context) {}

@Param 格式：@Param <name> <in> <type> <required> "<description>" [attributes]

<in>	用法
path	URL 路径段（/users/{id}）
query	URL 查询字符串（?filter=x）
body	请求体——类型必须是结构体
header	HTTP 头部
formData	多部分/表单字段

@Param 的可选属性：default(v), minimum(n), maximum(n), minLength(n), maxLength(n), Enums(a,b,c), example(v), collectionFormat(multi)。

@Success/@Failure 格式：@Success <code> {<kind>} <type> "<description>"

<kind>	适用场景
{object}	单个结构体
{array}	结构体切片
string / integer	基本类型

泛型（swag v2）：@Success 200 {object} api.Response[model.User]

嵌套组合：@Success 200 {object} api.Response{data=model.User}

安全定义

在 API 级别（main.go）定义一次，在每个端点上使用 @Security 应用。

// Bearer / JWT
// @securityDefinitions.apikey Bearer
// @in header
// @name Authorization

// API key in header
// @securityDefinitions.apikey ApiKeyAuth
// @in header
// @name X-API-Key

// Basic auth
// @securityDefinitions.basic BasicAuth

// OAuth2 authorization code
// @securityDefinitions.oauth2.authorizationCode OAuth2
// @authorizationUrl https://example.com/oauth/authorize
// @tokenUrl https://example.com/oauth/token
// @scope.read Read access
// @scope.write Write access

应用到端点：

// @Security Bearer
// @Security OAuth2[read, write]
// @Security BasicAuth && ApiKeyAuth   // AND — 两者都需要

结构体标签

在不改变 Go 类型的情况下丰富模型：

type CreateUserRequest struct {
    Name   string `json:"name" example:"Jane Doe" minLength:"2" maxLength:"100"`
    Role   string `json:"role" enums:"admin,user,guest" example:"user"`
    Age    int    `json:"age" minimum:"18" maximum:"120"`
    Avatar []byte `json:"avatar" swaggertype:"string" format:"base64"`
    Secret string `json:"-" swaggerignore:"true"`  // 从文档中排除
}

标签	用途
example	在 Swagger UI 中显示的示例值
enums	逗号分隔的允许值
swaggertype	覆盖检测到的类型（例如，time.Time 使用 "primitive,integer"）
swaggerignore:"true"	从生成的模式中排除字段
extensions	添加 OpenAPI 扩展：extensions:"x-nullable,x-deprecated=true"

常见错误

错误	原因	修复
缺少 _ "yourmodule/docs" 导入	模式未注册；UI 加载为空	在 main.go 或服务器初始化中添加空白导入
代码更改后 docs/ 未更新	文档与实现不一致；消费者获取错误模式	每次注解更改后重新运行 swag init
@Param body 使用基本类型	swag 无法从 string 推导模式；生成失败	始终为 body 参数使用命名结构体
受保护路由上没有 @Security	Swagger UI 不显示锁图标；测试者发送未认证请求	为每个需要认证的端点应用 @Security
通用信息注解在错误的文件中	swag 静默跳过；规范没有标题/主机	使用 -g <file> 标志或将注解移到 main.go
对映射类型使用 {object}	swag 无法为 map[string]any 生成模式	使用命名结构体或用 swaggertype 注解
多词 @Tags 未加引号	标签按空格分割，导致分组错误	对带空格的标签加引号：@Tags "user accounts"

交叉引用

• → 参见 samber/cc-skills-golang@golang-security 了解如何在生产环境中保护 Swagger UI 端点（禁用或使用认证中间件）。
• → 参见 samber/cc-skills-golang@golang-grpc 了解 gRPC——使用 grpc-gateway 及其自己的 OpenAPI 生成器，而不是 swag。

本技能并非详尽无遗。请参考 swaggo/swag 文档和代码示例以获取最新的 API 签名和使用模式。Context7 可作为发现平台提供帮助。有关 Go 包文档、版本、符号和已知漏洞，→ 参见 samber/cc-skills-golang@golang-pkg-go-dev 技能。

如果你遇到 swag 中的错误或意外行为，请在 https://github.com/swaggo/swag/issues 提交 issue。