Postman 不认 Go 生成的 OpenAPI JSON 主因是 $ref 未内联，需用 swag init --parseDependency 展开；导入必须通过 Postman API 推送内联 JSON 字符串，且字段名大小写须与前端请求严格一致。
Postman 不认 Go 生成的 OpenAPI JSON？先检查 swagger.json 的 $ref 是否内联
Postman 导入 OpenAPI 时卡在“解析失败”或只显示根路径，大概率是 Go 服务用 swaggo/swag 生成的 swagger.json 包含外部 $ref（比如指向 ./definitions/user.yaml）。Postman 只支持内联引用，不拉远程或本地文件。
- 用
swag init -o swagger.json --parseDependency强制展开所有$ref，别依赖默认行为 - 生成后手动 grep 一下：
grep -n '"\$ref"' swagger.json，有结果就得处理 - 如果用了
swaggo/echo-swagger或其他中间件，确认它 serve 的是磁盘上那个已内联的swagger.json，不是运行时动态拼的
Postman 工作空间同步靠 API，不是拖文件 —— 用 POST /workspaces/{workspace_id}/apis
手动 Import 文件只能进个人 Collection，没法自动更新、没版本控制、不触发团队同步。真要“自动同步”，必须走 Postman 的 REST API 把 swagger.json 推到指定工作空间的 API 定义里。
- 先在 Postman Web 界面创建一个空 API（类型选 OpenAPI），复制它的
api_id和所属workspace_id - 调用
POST https://api.getpostman.com/workspaces/{workspace_id}/apis，body 里带schema字段，值是整个swagger.json字符串（不是文件路径） - 记得加请求头：
Content-Type: application/json和X-API-Key: <your_postman_api_key>，API Key 在 Postman 账户设置里开 - 失败时看响应体里的
error.message，常见是invalid schema format—— 回头再验一遍 JSON 格式和内联引用
CI/CD 里自动推文档？绕不开 curl + jq 组合技
Go 微服务构建完，想顺手把最新文档扔进 Postman，就得在 CI 脚本里完成三件事：生成、校验、推送。别写复杂封装，curl 足够稳。
- 生成阶段加一句：
swag init -o docs/swagger.json --parseDependency --quiet - 校验阶段跑：
jq empty docs/swagger.json 2>/dev/null || { echo "swagger.json is invalid"; exit 1; } - 推送阶段用：
curl -X POST "https://api.getpostman.com/workspaces/$WORKSPACE_ID/apis" \ -H "X-API-Key: $POSTMAN_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"name\":\"my-service-api\",\"type\":\"openapi\",\"schema\":$(cat docs/swagger.json | jq -r tostring)}" - 注意
jq -r tostring是关键——把 JSON 原样转成字符串字面量，否则 Postman API 会当成对象嵌套解析出错
字段名大小写不一致？json:"user_id" 和 json:"userId" 在 Postman 里表现完全不同
Go struct tag 里的 json 字段名，直接变成 OpenAPI 的 property 名。Postman 自动生成 request body 示例、mock 响应、甚至测试脚本时，全按这个来。大小写一错，前端发的字段就进不了后端绑定。
立即学习“go语言免费学习笔记（深入）”；
- 查
swagger.json的components.schemas.*.properties下字段名，确认和你实际接收的 JSON key 一致 - 如果 Go 用的是
json:"user_id"，但前端传userId，要么改 Go tag（推荐json:"userId"），要么让前端改 —— 别指望 Postman 自动做映射 - 特别注意嵌套结构：比如
Address里有City string `json:"city"`，但在swagger.json里被错误渲染成cityName，那八成是某个中间层（如自定义swag注释或反射逻辑）偷偷改了名字
最麻烦的不是生成不出来，而是生成出来了但字段对不上——Postman 显示正常，请求却 400，这时候得翻 swagger.json 里每个 property 的真实 key，而不是只看 Go struct 名字。
