go-zero通过goctl api doc命令可自动生成OpenAPI 3.0文档：需v1.7.0+版本，执行goctl api doc -api xxx.api -dir ./docs生成JSON，或加-format html生成单页HTML，支持CI/CD自动更新。
要让团队成员或前端同事立刻看清接口字段、路径、参数位置和返回结构，不需要手动写 Markdown 或维护 Swagger Editor，go-zero 提供了开箱即用的文档生成能力，只要有一份定义清晰的 .api 文件，就能直接导出标准 OpenAPI 3.0 JSON 或 HTML 页面。
确认 goctl 已安装且版本支持 doc 命令
运行 goctl version，确保输出中包含 v1.7.0+（2025 年中起正式支持 goctl api doc）。低于该版本会提示 unknown command "doc"，此时必须升级： GOPROXY=https://goproxy.cn/,direct go install github.com/zeromicro/go-zero/tools/goctl@latest。
这一步不可跳过——旧版 goctl 即使能跑通 api new，也完全不识别 doc 子命令，强行使用会静默失败。
在项目根目录下执行文档生成命令
进入含 xxx.api 文件的目录（如 greet-api），执行：
goctl api doc -api greet.api -dir ./docs
命令会读取 greet.api，解析其中的 info 块、type 定义、service 路由与 handler 注解，生成 openapi.json 到 ./docs 目录。该 JSON 符合 OpenAPI 3.0.3 规范，可直接被 Swagger UI、Redoc 或 Stoplight 加载。
注意：【-api 参数必须指向真实存在的 .api 文件路径，不能是相对上级目录的 ../xxx.api，否则解析失败且无报错提示】。
快速预览 HTML 文档（无需部署服务）
方法一：用 goctl 内置静态页生成器
goctl api doc -api greet.api -format html -o ./docs/index.html
生成单文件 HTML，双击即可在浏览器打开，含完整路径列表、请求体折叠展示、响应示例高亮。
方法二：配合本地 Swagger UI
先生成 JSON：goctl api doc -api greet.api -o ./docs/openapi.json；再下载 Swagger UI dist，把 dist 目录放到 ./docs 下，修改 index.html 中 url 指向 ./openapi.json，用 Python 快速起服务：python3 -m http.server 8000，访问 http://localhost:8000 即可交互式调试。
这一步操作起来很简单，直接把文件拖进去就行。但要注意：如果 .api 里没写 info 块，生成的 HTML 标题会显示 “undefined”，建议至少补上 title 和 version。
对接 CI/CD 自动更新文档
第一步：在 CI 脚本中加入生成指令
goctl api doc -api user.api -o /tmp/openapi.json
第二步：校验 JSON 是否合法（避免因 .api 语法错误导致文档失效）
jq empty /tmp/openapi.json || { echo "openapi.json is invalid"; exit 1; }
第三步：上传至文档托管平台（如 GitHub Pages 的 docs/ 分支）
cp /tmp/openapi.json $GITHUB_WORKSPACE/docs/
每次 push .api 文件就触发构建，文档永远与最新接口定义一致。不用人工同步，也不会出现“前端按文档调用却 400”的尴尬。
