swag 是 Go 最成熟的 OpenAPI 文档生成工具,通过解析源码注释生成 swagger.json;需在项目根目录执行 swag init,handler 函数须带完整注释块且紧贴声明,结构体字段需 json tag,Gin/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/swag@latest(注意:不是 go get,新版 Go 已弃用)所有 HTTP handler 函数(如 GetUsers)必须有完整的 // @Summary、// @Success 等注释块,且注释必须紧贴函数声明上方,中间不能有空行结构体字段若要出现在请求/响应示例中,需带 json tag,例如 Name string `json:"name"`;否则 swag 无法推导字段名和类型如果用的是 Gin、Echo 或 net/http,swag 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视频编辑工具,可以帮助用户轻松重写、配音和编辑视频。
相关推荐
2601_9679801111 分钟前
python+appium自动化测试如何控制App的启动和退出顧棟1 小时前
【ES实战】 索引模板「可追溯、可校验」:一种模板治理的工程化思路威哥爱编程1 小时前
模拟面试智能体开发实战 12:每篇都能跑不等于接起来能跑,端到端联调收官把十一块拼图合成一个能用的智能体威哥爱编程1 小时前
模拟面试智能体开发实战 11:报告只躺在后端怎么复盘,把总评搬上手机还要适配大小屏Decay__2 小时前
SQLServer 监控体系构建 —— sql_exporter + Prometheus + Grafana 全栈实战2601_967987372 小时前
Python 实现行为驱动开发 (BDD) 自动化测试详解tianyuanwo2 小时前
NocoDB 系统手册:PostgreSQL 主机资产管理的界面层实施方案Umi·3 小时前
MySQL之多表关联查询练习实泽有之,无泽虚之3 小时前
Windows环境bat脚本自动备份MySQL数据库并清理旧备份文件数字融合3 小时前
透明化视频驱动化工生产动态三维重建管控技术