Go mod 好菜系列 - 0x0E swaggo 这盘接口文档别再靠手写了
详细讲 swaggo 如何从注释生成 Swagger/OpenAPI 文档、它适合什么团队流程，以及怎样避免文档和代码一起失真。
只要项目开始有前后端协作、接口越来越多、联调越来越频繁，接口文档就会从“有空再补”迅速变成“再不补就要互相猜”。而所有靠手工维护的文档，最后大概率都会走向一个结局：代码已经改了，文档还在描述上周的世界。
swaggo 是来干嘛的
它最核心做的事，就是根据你在代码里的注释，生成 Swagger/OpenAPI 文档。换句话说，它试图让接口文档尽量贴着代码长，而不是跑去另一个地方单独养。
为什么它常见
因为它刚好击中一个非常现实的痛点：
- 前端想看接口文档
- 后端不想再维护一套手工文档
- 项目又希望文档至少别完全失真
swaggo 不是完美答案，但它确实让很多团队把“文档至少能用”这件事往前推了一步。
它的工作流大概是什么
- 你在 handler 附近写注释
- 跑生成命令
- 项目里挂 Swagger UI
- 大家通过页面看接口说明
关键不在生成命令有多炫，而在“接口变动时，文档更新成本能不能低到让大家愿意做”。
一个典型注释会长这样
// GetUser godoc
// @Summary 获取用户详情
// @Description 根据用户 ID 查询详情
// @Tags users
// @Param id path int true "用户ID"
// @Success 200 {object} UserResp
// @Router /users/{id} [get]
func GetUser(c *gin.Context) {
// ...
}说白了，它就是在用一套约定注释，去补接口元信息。
它最适合什么团队状态
- 接口数量开始上来了
- 前后端联调频繁
- 团队能接受在代码边上多写一点注释约定
- 希望文档生成流程尽量自动化
小项目、单人项目当然也能用，但它真正价值通常在协作场景里更明显。
它并不自动保证文档真实
这点特别重要。很多人以为“文档生成于代码”就天然正确，其实并不是。因为注释本身还是人写的，人一样可能忘改、乱写、写得过时。
swaggo 解决的是“文档生成和展示流程”，不是“人永远不犯错”。
怎么才能让它真正有用
- 把注释写在 handler 边上
- 把生成命令放进开发流程或 CI
- 接口改动时，把更新注释当成同一个动作
- 别把文档当交差材料，而是当联调工具
如果只是生成一次放那儿吃灰，那它和手写文档烂尾的区别也没那么大。
小结
swaggo 不是“写文档的终极解药”，但它确实很适合 Go API 项目的现实协作节奏：
- 它能让接口文档更贴近代码
- 特别适合前后端频繁联调的项目
- 文档最终靠的是流程和习惯，不是工具魔法
- 它解决的是文档维护成本，不是文档真实性的所有问题
下一篇我们讲 prometheus/client_golang。日志告诉你“发生了什么”，指标则更像在告诉你“整体状态正往哪边走”。
