本文介绍如何通过 Go 源码中的结构化注释，结合 swag 或 goswagger 工具自动生成 OpenAPI（Swagger）规范文件，重点说明默认输出 JSON 的原因、生成命令的正确用法，并提供 YAML 转换方案与最佳实践。
本文介绍如何通过 go 源码中的结构化注释，结合 `swag` 或 `goswagger` 工具自动生成 openapi（swagger）规范文件，重点说明默认输出 json 的原因、生成命令的正确用法，并提供 yaml 转换方案与最佳实践。
Go 生态中主流的 Swagger 规范生成工具主要有两类：goswagger（基于 OpenAPI 2.0/3.0，命令行驱动）和 swag（即 swaggo/swag，轻量级、支持 OpenAPI 3.1，更受现代项目青睐）。二者均依赖源码中的特定注释（如 // @title, // @version, // @router 等）提取 API 元数据。
⚠️ 注意：goswagger generate spec 默认仅生成 JSON 格式 的 OpenAPI 文档（如 swagger.json），不原生支持直接输出 .yaml 文件。这是由其设计决定的——官方文档明确指出当前版本未实现 YAML 输出选项。
✅ 正确生成 JSON 规范的步骤如下：
-
在 main.go（或主包入口文件）顶部添加生成指令注释：
//go:generate swagger generate spec -o ./docs/swagger.json --default-scheme https //go:generate go run github.com/go-openapi/loads/cmd/validate ./docs/swagger.json
-
确保已安装 goswagger CLI（需 Go 1.16+）：
curl -sSfL https://raw.githubusercontent.com/go-swagger/go-swagger/master/install.sh | sh -s -- -b /usr/local/bin # 或使用 Go install（推荐） go install github.com/go-swagger/go-swagger/cmd/swagger@latest
运行生成命令：
- 若 main.go 位于项目根目录（./main.go）：
go generate
- 若主包位于子目录（如 cmd/my-server/main.go），需显式指定路径：
go generate ./cmd/my-server
生成后，./docs/swagger.json 即为标准 OpenAPI 3.0 兼容的 JSON 规范文件，可直接用于 Swagger UI、Redoc 或 API 网关集成。
? 如何获得 YAML 版本？
虽 goswagger 不直接支持 -o *.yaml，但可通过以下任一方式安全转换：
- 使用 jq（推荐，保留格式与注释）：
jq -r 'tostring' docs/swagger.json | yq -p json -P > docs/swagger.yaml
- 或借助在线/本地工具（如 swagger-cli bundle --format yaml 或 VS Code 插件）进行无损转换。
? 进阶建议：
- 对新项目，更推荐使用 swaggo/swag（swag init 命令），它默认支持 --output 指定 YAML 目录，且注释语法更简洁、兼容性更好；
- 所有注释必须置于函数或结构体上方，且 // @host, // @basepath 等全局配置须在 main 包中定义；
- 运行 go generate 前请确保所有依赖已 go mod tidy，避免因类型解析失败导致生成中断。
最终，一份可部署的 Swagger 文档不仅提升协作效率，更是 API 可观测性与契约测试的基础——从注释开始，让文档与代码真正同步演进。
