Postman 怎样从 OpenAPI 导入接口集合

手里已经有 OpenAPI 文件，却不想在 Postman 里一条条新建请求时，最省事的入口是直接导入规格。Postman 当前支持 OpenAPI 2.0、3.0 和 3.1；导入来源可以是单文件、多文件目录、可访问链接或粘贴的原始文本。关键在于导入后要先分清“只生成接口集合”和“同时保留规格与集合”两个结果。

官方地址：https://learning.postman.com/docs/design-apis/specifications/import-a-specification/

如果你的目标只是马上得到可发送的请求树，选择 Postman Collection；如果还要继续维护 API 规格并让规格和请求集合保持协作关系，选择 Specification with a Postman Collection。入口都从侧边栏的 Import 开始。

先把 OpenAPI 来源准备好

我通常先判断手里的定义属于哪一种来源，再打开 Postman。一个完整的单文件规格可以是 YAML 或 JSON；如果文件使用了多个相互引用的文件，则更适合把目录作为整体交给导入器。Postman 官方文档也支持直接输入规格链接，或者粘贴原始 JSON/YAML。

可以用下面这段最小 OpenAPI 结构确认自己拿到的是“接口规格”，而不是只包含一段响应示例的普通 JSON。JSON 块保持严格合法，字段含义在正文中解释。

{
  "openapi": "3.0.3",
  "info": {
    "title": "库存服务",
    "version": "1.0.0"
  },
  "paths": {
    "/items": {
      "get": {
        "responses": {
          "200": {
            "description": "返回库存列表"
          }
        }
      }
    }
  }
}

openapi 表明规格版本，info 提供名称和版本，paths 才是请求集合能够展开的接口入口。实际项目里还可能有 components、安全方案和外部引用；不要为了“看起来简单”把这些字段先删掉。

从侧边栏打开 Import

打开 Postman 后，先看左侧工作区导航，而不是先创建一个空集合。点击侧边栏的 Import，导入面板会把来源分成几类：

1. Files：选择单个 OpenAPI YAML 或 JSON 文件。
2. Folder：选择包含多文件 OpenAPI 定义的目录。
3. Link：输入可以读取规格内容的地址。
4. Raw text：直接粘贴 OpenAPI 文本。

如果你只有一个文件，优先使用 Files，定位问题最直接；如果规格里有相对路径引用，使用 Folder 能保留文件之间的关系。选择来源后，先停在预览区域看识别结果，别在格式尚未识别时连续点击提交。

让 Postman 识别规格并选择导入方式

选择文件或输入内容后，Postman 会进入规格识别界面。这里真正需要做决定的是生成目标，而不是再次选择 HTTP 方法：

• Postman Collection：把 OpenAPI 中的路径和操作生成请求文件夹与请求项，适合马上联调或交给测试同事使用。
• Specification with a Postman Collection：在生成请求集合的同时保留一个规格对象，适合还要继续设计、评审或维护 API 定义的团队。

两者都可以产生接口集合，但第二种会把“规格”和“请求”作为两个有关联的工作对象保存。若团队已经把 OpenAPI 当作契约，选择第二种更容易继续维护；若只是把一份外部规格转换成临时请求清单，第一种更轻量。

导入完成后检查集合树和规格归属

点击 Import 后，不要只看弹窗是否消失。回到工作区侧边栏，按下面三个位置快速核对：

1. 集合树中是否出现以 API 名称命名的新集合，以及按标签或路径组织的请求文件夹。
2. 随机展开一个请求，确认方法、路径参数和响应说明来自规格，而不是空白请求模板。
3. 如果选择了 Specification with a Postman Collection，再确认规格对象也出现在预期的 Spec Hub 或工作区位置。

这一步的目的是确认“导入对象落在哪里”。如果只看到集合，没有看到规格，通常是选择了只生成 Collection 的路径；这不一定是失败，而是导入目标不同。

三个容易走错的地方

把普通 JSON 当成 OpenAPI。只有响应示例、环境变量或接口返回样本不能自动变成完整请求集合。先确认有 openapi 或符合规格版本的根结构。

多文件规格只选了根文件。如果定义依赖同目录下的引用文件，优先通过 Folder 导入；否则识别阶段可能无法展开完整的 schema 或路径。

把两种导入结果混为一谈。Collection 解决的是请求组织和调用入口，Specification 解决的是接口契约的持续维护。根据协作目标选择，不要因为“请求已经生成”就默认规格对象也会同时存在。

常见问题

OpenAPI 文件是 YAML，可以直接导入吗？

可以。Postman 官方文档列出的规格导入支持 YAML 和 JSON；单文件可通过 Files 选择，多文件定义可选择对应目录。

导入后为什么只有请求，没有规格页面？

检查导入时是否选择了 Postman Collection。若希望同时创建规格和集合，需要在识别结果中改选 Specification with a Postman Collection，然后再提交。

结语

Postman 导入 OpenAPI 的核心不是“把文件拖进去”，而是先选对来源，再选对生成目标。单文件用 Files，多文件引用用 Folder，远程定义用 Link，临时内容用 Raw text；最后根据团队是否继续维护 API 契约，在 Collection 和 Specification with a Postman Collection 之间做选择，导入后的集合结构就更容易和实际工作流对齐。