作为一名与 API 交互的开发者，你可能对 Postman 并不陌生，它是一个用于测试和记录端点的常用工具。 然而，当涉及到以像 OpenAPI 3.0 这样的标准化格式共享你的 API 文档时，你可能会感到无所适从。
别担心！ 这份全面的指南将引导你完成将 Postman 集合转换为 OpenAPI 3.0 规范的过程，重点介绍流行的 postman-to-openapi npm 包。
为什么要将 Postman 转换为 OpenAPI？
在开始之前，让我们快速了解一下为什么要将 Postman 集合转换为 OpenAPI：
- 标准化 (Standardization)：OpenAPI 是描述 RESTful API 的行业标准，确保你的文档一致且易于其他开发人员理解。
- 互操作性 (Interoperability)：许多工具和平台都支持 OpenAPI，从而更容易与其他系统和服务集成。
- 文档 (Documentation)：OpenAPI 为 API 文档提供了一种清晰、人类可读的格式，使其他人更容易理解和使用你的 API。
- 代码生成 (Code Generation)：你可以使用 OpenAPI 规范来生成客户端库和服务器存根，从而简化你的开发过程。
现在，让我们来探索如何实现这种转换！
使用 postman-to-openapi：一步一步指南
postman-to-openapi npm 包是一个强大的工具，用于将 Postman 集合转换为 OpenAPI 3.0 规范。 这是一个关于如何使用它的分步指南：
步骤 1：通过 npm 安装 postman-to-openapi 包
首先，你需要安装这个包。 打开你的终端并运行：
npm install postman-to-openapi或者如果你更喜欢 yarn：
yarn add postman-to-openapi步骤 2：在 Node.js 中使用 postman-to-openapi
安装完成后，你可以在你的 Node.js 项目中使用这个包。 这是一个简单的例子：
const postmanToOpenApi = require('postman-to-openapi')
const postmanCollection = './path/to/your/collection.json'
const outputFile = './output/openapi.yml'
async function convertCollection() {
try {
const result = await postmanToOpenApi(postmanCollection, outputFile, {
defaultTag: 'General'
})
console.log(`OpenAPI specs: ${result}`)
} catch (err) {
console.error('Conversion failed:', err)
}
}
convertCollection()此脚本会将你的 Postman 集合转换为 OpenAPI 3.0 YAML 文件。
步骤 3：postman-to-openapi 的自定义用法
postman-to-openapi 包提供了几个选项来自定义你的转换。 这里有一些有用的选项：
defaultTag：为所有操作设置一个默认标签（默认为 'default'）。outputFormat：在 'yaml' 或 'json' 之间选择（默认为 'yaml'）。includeAuthInfoInExample：在示例中包含身份验证信息（默认为 false）。
让我们修改我们的脚本来使用这些选项：
const postmanToOpenApi = require('postman-to-openapi')
const postmanCollection = './path/to/your/collection.json'
const outputFile = './output/openapi.json'
async function convertCollection() {
try {
const result = await postmanToOpenApi(postmanCollection, outputFile, {
defaultTag: 'MyAPI',
outputFormat: 'json',
includeAuthInfoInExample: true
})
console.log(`OpenAPI specs: ${result}`)
} catch (err) {
console.error('Conversion failed:', err)
}
}
convertCollection()此脚本将输出一个 JSON 文件，其中示例中包含身份验证信息，并且所有操作都标记为 'MyAPI'。
如果我不想使用 postman-to-openapi 包怎么办？
虽然 postman-to-openapi 包非常适合简单的转换，但有时你可能需要更多的控制或有特定的要求。 让我们探索一些高级技术。
选项 1：使用 Apifox 进行 Postman 到 OpenAPI 的转换
Apifox 是另一个出色的工具，可以帮助你将 Postman 集合转换为 OpenAPI 格式。 这是一个关于如何使用它的快速指南：
- 登录到 Apifox 并导航到“设置”菜单。
- 从选项中选择“导入”。
- 选择你要导入的 Postman 集合文件。 Apifox 将导入并转换你的集合，允许你查看和编辑生成的 API 文档。
将你的 Postman 集合导入到 Apifox
- 点击“导出数据 (Export Data)”按钮，然后选择导出为 OpenAPI 3.0 格式。
将你的 Postman 数据导出为 OpenAPI 3.0 格式
但是等等，Apifox 不仅仅是一个 Postman 集合到 OpenAPI 格式的转换器。 它是一种易于使用的替代方案，让你忘记为 Postman Enterprise 付费。
Apifox 提供其他功能，如 API 测试和模拟服务器，使其成为 API 开发和文档的综合解决方案。 这是你从 Apifox 获得的，而不是订阅每月 19 美元的 Postman：
- 无限制的 API 创建
- 没有流量限制和无限的集合运行器运行
- 无限制的 API 调用
- 无限制的 API 模拟服务器调用
这些都可以在 Apifox 免费版本 中使用！
安全保证，无广告
选项 2：使用 Postman API 进行转换
Postman 本身提供了一个 API，可以将集合转换为 OpenAPI 格式。 这是你如何使用它的：
- 从你的帐户设置中获取你的 Postman API 密钥。
- 使用以下 curl 命令（用你的实际值替换占位符）：
curl --location --request GET 'https://api.getpostman.com/collections/{{collectionId}}/transformations' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{postman-api-key}}'- 响应将包含 OpenAPI 规范。 你可以将其保存到文件中以供进一步使用。
选项 3：用于 Postman 到 OpenAPI 转换的在线工具
如果你喜欢快速、无代码的解决方案，你可以使用一些在线工具进行快速转换。 这是一个关于如何使用它的例子：
- 从可用的 一个免费的在线工具 中选择。
- 上传你的 Postman 集合 JSON 文件或粘贴集合 URL。
- 单击“转换 (Convert)”并下载生成的 OpenAPI 规范。
此方法非常适合一次性转换，或者当你不想设置开发环境时。
如何轻松地将 Postman 转换为 OpenAPI：提示和最佳实践
即使使用最好的工具，你可能也会遇到一些小问题。 这里有一些常见问题及其解决方案：
- 拆分集合 (Splitting Collections)：将大型集合分成更小、更易于管理的部分。 这种方法可以更轻松地转换和维护生成的 OpenAPI 规范。
- 使用文件夹 (Using Folders)：使用文件夹组织你的 Postman 集合以创建逻辑结构。 这将有助于生成组织良好的 OpenAPI 规范，并使其更易于导航。
- API 转换器 (API Transformer)：利用像 API Transformer 这样的工具，它可以处理大型 Postman 集合并将它们有效地转换为 OpenAPI 规范。
- OpenAPI 验证 (OpenAPI Validation)：转换后验证你的 OpenAPI 规范，以确保它是正确和完整的。 这一步对于识别转换过程中可能出现的任何问题至关重要。
因此，为了确保顺利的转换过程，请记住以下提示：
- 清理你的 Postman 集合 (Clean Your Postman Collection)：在转换之前，检查你的集合是否存在任何不一致或不必要的元素。
- 使用描述性名称 (Use Descriptive Names)：确保你的端点、参数和响应在 Postman 中具有清晰、描述性的名称。
- 包括示例 (Include Examples)：在 Postman 中添加示例响应以丰富你的 OpenAPI 文档。
- 使用文件夹组织 (Organize with Folders)：使用 Postman 中的文件夹以逻辑方式对你的端点进行分组，这将转换为 OpenAPI 中的标签。
- 验证输出 (Validate the Output)：转换后，使用 OpenAPI 验证器以确保生成的规范有效。
结论
将 Postman 集合转换为 OpenAPI 规范是标准化 API 文档和确保与其他系统无缝集成的关键一步。
通过遵循本指南中概述的步骤，你可以有效地转换你的 Postman 集合并利用 OpenAPI 提供的优势。
常见问题 (FAQs)
问：将 Postman 集合转换为 OpenAPI 规范的主要好处是什么？
答：主要好处是标准化，这使得与其他系统和工具的集成更容易。
问：我可以使用在线工具进行 Postman 到 OpenAPI 的转换吗？
答：是的，可以使用像 p2o.defcon007.com 和 Apifox 这样的在线工具将 Postman 集合转换为 OpenAPI 规范。
问：在转换过程中，我如何处理大型 Postman 集合？
答：大型集合可以分成更小的部分，使用文件夹组织，或使用像 API Transformer 这样的工具进行转换。
问：转换后是否有必要验证 OpenAPI 规范？
答：是的，在转换后验证 OpenAPI 规范至关重要，以确保它是正确和完整的。