OpenAPI驱动Postman

你平时用 Postman 测接口：每加一个接口，就在左侧 New → HTTP Request，自己填 URL、选 GET/POST、手写 JSON。项目有 20 个接口时，你要点 20 遍；同事改路径后，你手里的 Postman 还是旧的，Send 出去 404，却不知道改哪。

1. 两个词：Postman 和 openapi.json

1.1 Postman 是什么？

Postman 是一个点按钮发 HTTP 请求的工具（类似在浏览器地址栏访问网址，但能改方法、Header、Body）。

你以前做的：

左侧 Collections → 自己新建请求 → 填 http://localhost:8080/health → Send

1.2 openapi.json 是什么？

可以把它想成一份 「接口清单」，用 JSON 写清楚：

• 有哪些路径（如 /health）
• 每个路径支持 GET 还是 POST
• POST 的 body 长什么样

很多团队会让这份清单和真实代码保持一致。Postman 可以从这份清单批量生成请求，而不是你一个个手填。

你不需要会写完整 OpenAPI 规范；跟做时直接复制下面这一小段即可。

2. 跟做：5 分钟在 Postman 里「长」出 2 个请求

2.1 准备软件

软件	用来干什么	怎么确认装好了
Postman 桌面版	导入并发送请求	能打开，左侧有 Collections
Node.js（带 npx）	把 openapi 转成 Postman 能吃的文件	终端执行 npx --version 有版本号

不需要安装 Postman CLI，主路径用不到。

2.2 新建 Mini 接口清单

在任意空文件夹里新建 mini-openapi.json，粘贴下面内容（虚构的小 API，和具体公司项目无关）：

{
  "openapi": "3.0.3",
  "info": { "title": "Demo API", "version": "1.0.0" },
  "servers": [{ "url": "http://localhost:8080" }],
  "paths": {
    "/health": {
      "get": {
        "summary": "健康检查",
        "responses": { "200": { "description": "OK" } }
      }
    },
    "/users/login": {
      "post": {
        "summary": "用户登录",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "username": { "type": "string" },
                  "password": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "OK" } }
      }
    }
  }
}

保存后，你的文件夹里至少有两个东西：mini-openapi.json 和等会生成的 collection 文件。

2.3 一条命令：清单 → Postman 文件

在该文件夹打开终端，执行：

npx --yes openapi-to-postmanv2@5.0.0 \
  --spec ./mini-openapi.json \
  --output ./demo.postman_collection.json \
  --pretty

正常情况：命令结束没有报错，目录里多出 demo.postman_collection.json。

如果报错 npx: command not found：先安装 Node.js，再重试。

2.4 导入 Postman 桌面版

1. 打开 Postman → 左上角 Import
2. 选 Upload Files → 选中 demo.postman_collection.json
3. 点 Import 确认

你应该看到（和下面类似即可，名称可能略有差别）：

Collections
  └── Demo API          ← 来自 json 里的 info.title
        ├── GET  健康检查      → http://localhost:8080/health
        └── POST 用户登录      → http://localhost:8080/users/login

点开 POST 用户登录，Body 里已经有 username、password 字段——这些是从 mini-openapi.json 里读出来的，不是你手打的。

2.5 点 Send 会怎样？（这步失败也算成功）

如果你没有在 localhost:8080 跑任何服务，点 Send 通常会报 Could not send request 或连接失败——这很正常。

本节的胜利条件是：

• ✅ 左侧出现了 2 个请求
• ✅ 点开能看到对的 URL、Method、Body
• ❌ 不要求返回 200

以后后端起来了，同一个请求再 Send 就能通。你省掉的是「手建 20 遍请求」的时间。

3. 你刚才到底做了什么？（拆成 3 步）

mini-openapi.json     「接口清单」（你维护的源头）
        │
        │  npx openapi-to-postmanv2
        ▼
demo.postman_collection.json   「Postman 导入包」（可随时重新生成）
        │
        │  Postman Import
        ▼
左侧 Collections 里的请求    「调试用的副本」

记住一句就够：

改接口时，改清单（openapi.json），再重新生成并 Import；不要把 Postman 里改 URL 当成全队的正式改法。

原因很简单：下次有人重新生成时，你在 UI 里手改的路径会被覆盖掉。

4. 和「纯手工 Postman」比，你多了什么？

纯手工	OpenAPI 驱动
新接口 = 再点一次 New Request	新接口 = 清单里加一段，再跑一条 npx + Import
路径改了，要自己找是哪个请求	重新生成，请求会跟着清单变
容易和代码、文档各写各的	清单可以成为团队共认的「接口说明」

你不需要一步到位上 CI、Makefile、Cloud。会 清单 → npx → Import 就已经比纯手建省很多事。

5. 可选进阶：真项目为什么要更复杂？

上面是小白主路径：一个 JSON 文件 + 桌面 Import，最简单。

如果一个项目有 100+ 接口：

• 从 Go 代码自动生成 docs/openapi.json（make openapi）
• 转成 Postman 的 Native Git 目录（每个请求一个 .yaml，方便脚本改）
• 用脚本给需要登录的接口自动加 Bearer {{access_token}}，登录接口自动把 token 写入环境变量
• 生成和推到 Postman 云分开：make postman-collection vs make postman-sync

那条链大致是：

docs/openapi.json
  → openapi-to-postmanv2
  → postman collection migrate
  → postprocess_postman_collection.js
  → postman/collections/...   （本地生成，默认不进 Git）
  → postman workspace push    （可选，给团队用 Cloud）

你若已在类似团队，只要记住主路径里的原则一样：清单是源头，Postman 是生成物。Makefile 只是把 npx + Import 包装成一条 make postman-collection。

想调通真实登录（可选 A2）：本地或 Dev 环境起服务 → Postman 里配好 Environment 的 baseUrl → 先调登录接口 → 再调带鉴权的业务接口。细节见项目 backend/README.md 的 Postman 一节。

OpenAPI 规范本身（Code-First / Design-First、和 Swagger 啥关系）见同站《OpenAPI 和 Swagger 基础》。

6. 常见问题

Q：我没有 openapi.json，只有 Word 文档怎么办？
先让团队有一份机器可读的清单（哪怕从现有 Postman 导出再慢慢迁）。没有清单就没有自动生成。

Q：Import 后 Send 一直失败？
主路径不要求通。检查：服务是否启动、URL 是否是 http://localhost:8080、防火墙。

Q：同事在 Postman 里改了 URL，我重新生成会怎样？
他的修改会被新生成的覆盖。正式变更应改 openapi（或改代码再生成 openapi），然后大家重新 Import 或走团队的 Cloud 同步。

Q：我还要学 Native Git、migrate 吗？
不用。那是大项目为了脚本化、少 diff 噪音用的。你掌握 npx + Import 就够入门。

7. 小结

1. openapi.json = 接口清单（源头）
2. npx openapi-to-postmanv2 = 清单转成 Postman 导入包
3. Postman Import = 左侧一次性出现很多请求
4. 别在 UI 里当正式文档改路径；接口变了就改清单再生成

今天跟做用的清单只有 2 个接口；真项目只是把「2」换成「200」，道理相同。

参考资料

• Postman 下载
• openapi-to-postmanv2（npm）
• 同站：OpenAPI 和 Swagger 基础