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                        # generates docs/ with docs.go, swagger.json, swagger.yaml
swag init -g cmd/api/main.go     # if general info is not in main.go
swag fmt                         # format annotation comments (like go fmt)

导入 docs 包以注册规范。若只需接入 UI，请使用空白导入；若还需在运行时覆盖 docs.SwaggerInfo，请使用具名导入：

import _ "yourmodule/docs"          // blank: registers spec, no identifier
import docs "yourmodule/docs"       // named: use when overriding 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     Short description of the API.
// @host            localhost:8080
// @BasePath        /api/v1
// @schemes         http https

// @contact.name    API Support
// @contact.email   [email protected]
// @license.name    Apache 2.0

// @securityDefinitions.apikey Bearer
// @in header
// @name Authorization
// @description Type "Bearer" followed by a space and the JWT token.

操作注释

为每个处理函数添加注释。标准文档注释（// FuncName godoc）必须放在 swag 注释之前——它为 swag fmt 锚定缩进。

// ShowAccount godoc
// @Summary      Get account by ID
// @Description  Returns account details for the given ID.
// @Tags         accounts
// @Accept       json
// @Produce      json
// @Param        id      path  int  true  "Account ID"
// @Param        filter  query string false "Optional search filter"
// @Success      200  {object}  model.Account
// @Success      204  "No content"
// @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 — both required

结构体标签

无需更改 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"`  // excluded from docs
}

标签	用途
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 推导架构；生成失败	正文参数始终使用命名结构体
受保护路由未添加 @Security	Swagger UI 不显示锁定图标；测试人员会发送未经身份验证的请求	为每个需要身份验证的端点添加 @Security
通用信息注释放在错误的文件中	swag 会静默跳过这些注释；规范没有标题/主机	使用 -g <file> 标志，或将注释放到 main.go 中
对 map 类型使用 {object}	swag 无法在没有辅助信息的情况下为 map[string]any 生成架构	使用命名结构体，或使用 swaggertype 注释
多词 @Tags 未加引号	标签会按空格拆分，导致分组格式错误	为包含空格的标签加引号：@Tags "user accounts"

交叉引用

• → 有关如何在生产环境中保护 Swagger UI 端点（通过身份验证中间件禁用或限制访问），请参阅 samber/cc-skills-golang@golang-security。
• → 有关 gRPC，请参阅 samber/cc-skills-golang@golang-grpc：使用 grpc-gateway 及其专用的 OpenAPI 生成器，而不是 swag。

此技能并未涵盖所有内容；如需了解最新的 API 签名和用法模式，请参阅 swaggo/swag 文档和代码示例：

• 如需了解 Go 包的文档、符号、版本、导入方和已知漏洞，请参阅 samber/cc-skills-golang@golang-pkg-go-dev 技能（godig）；查询 Go 包信息时，优先使用此技能而非 Context7。
• 如需在自己的代码中查找此库的用法（定义、调用位置、诊断信息），请参阅 samber/cc-skills-golang@golang-gopls 技能（gopls）。
• 对于 pkg.go.dev 未收录的文档，Context7 仍可作为备用方案。

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