Go语言如何做API文档生成_Go语言API文档自动生成教程【收藏】

swag 是 Go 最成熟的 OpenAPI 文档生成工具通过解析源码注释生成 swagger.json需在项目根目录执行 swag inithandler 函数须带完整注释块且紧贴声明结构体字段需 json tagGin/Echo 需手动注入 Swagger UI 路由。Go 语言本身不内置 API 文档生成器但 swag 是目前最成熟、与 Go 原生风格兼容性最好的方案——它通过解析源码中的特定注释而非反射或运行时分析生成符合 OpenAPI 3.0 规范的 swagger.json再交由 Swagger UI 渲染。别指望 godoc 或 go doc 能输出 REST API 文档它们只管包/函数说明。用 swag init 生成 swagger.json 的前提条件必须在项目根目录即包含 main.go 或 server.go 的目录执行 swag init否则会报 cannot find main.go 或扫描不到 handler 函数。swag 命令行工具需先安装go install github.com/swaggo/swag/cmd/swaglatest注意不是 go get新版 Go 已弃用所有 HTTP handler 函数如 GetUsers必须有完整的 // Summary、// Success 等注释块且注释必须紧贴函数声明上方中间不能有空行结构体字段若要出现在请求/响应示例中需带 json tag例如 Name string json:name否则 swag 无法推导字段名和类型如果用的是 Gin、Echo 或 net/httpswag init 都能识别但路由注册方式不影响解析——它只看函数签名和注释不分析 r.GET() 这类调用常见注释写法与易错点swag 对注释格式极其敏感一个标点错误就会导致字段丢失或生成失败。比如 Param 后必须跟参数名、类型、位置path/query/body、是否必需缺一不可。// Param id path int true user ID ? 正确路径参数 id类型 int位置 path// Param id query string true user ID ? 查询参数类型写 string不是 string 加引号// Success 200 {object} model.User ? 响应体是结构体指针或值均可但 model.User 必须可被导入即所在包已 import错误写法// Success 200 {object} User ? 没带包名swag 找不到定义或写成 {array} 却没指定元素类型如 {array} model.User 才对集成到 Gin/Echo 服务并暴露 Swagger UI生成 docs/ 目录后需手动把文档路由注入 HTTP 服务。这步不能跳过否则访问 /swagger/index.html 会 404。 Vozo Vozo是一款强大的AI视频编辑工具可以帮助用户轻松重写、配音和编辑视频。