Gin API 文档：用 Swagger/OpenAPI 自动生成

1. 为什么写文档

前端对接、客户端联调、第三方接入，都靠一份准的接口文档。手写文档和代码容易不同步，注解写代码里，生成的就是最新的。

2. 安装与初始化

go install github.com/swaggo/swag/cmd/swag@latest
go get github.com/swaggo/gin-swagger
go get github.com/swaggo/files

在 main.go 上方写全局注解：

// @title Gin Demo API
// @version 1.0
// @BasePath /api/v1

跑 swag init 生成 docs/ 目录。

3. handler 注解

每个接口写注解，swag 自动拼成 OpenAPI：

// GetArticle godoc
// @Summary 获取文章详情
// @Param id path string true "文章 ID"
// @Success 200 {object} Result{data=Article}
// @Router /articles/{id} [get]
func (h *ArticleHandler) Get(c *gin.Context) { ... }

@Param 标路径/查询/body 参数，@Success 标返回结构。改了代码顺手改注解，swag init 出新版。

4. 挂 UI

import "github.com/swaggo/gin-swagger"

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

访问 /swagger/index.html 看到可交互 UI，能直接填参数发请求试。

5. 接统一响应

第 4 篇的 Result 包络直接当返回结构，文档里就能显示统一格式：

// @Success 200 {object} Result{data=Article}

前端一看就知道成功是 code=0、数据在 data。多个接口复用同一 Result，文档风格一致。

6. 生产收口

文档暴露所有接口细节，生产别开。按环境决定是否挂路由：

if cfg.Env != "prod" {
    r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
}

或者只在内网域名挂。网关层对 /swagger 加访问控制。

7. 上线清单

注解写在 handler 上方，改接口同步改注解。统一响应结构复用 Result，文档风格一致。swag init 进 CI，文档和代码一起出。生产默认不挂 swagger UI，或只内网可见。接口变更先更注解再发版，别代码动了文档旧。

下一篇讲性能调优，用 pprof 把慢在哪看清楚。