从Swagger迁移至Postman：拆分YAML文件无法导入的问题

Postman无法直接解析带$ref引用的拆分式Swagger YAML文件，以下是三种可行的导入方案：

方法1：合并拆分YAML文件（推荐） #

通过工具将所有分散的YAML文件合并为一个完整的Swagger/OpenAPI文件，再导入Postman：

• 使用swagger-cli工具（基于Node.js）：
  1. 全局安装工具：

     npm install -g swagger-cli
     

  2. 执行合并命令（假设主Schema文件名为main.yaml）：

     swagger-cli bundle main.yaml -o merged-swagger.yaml -t yaml
     

     该命令会自动解析所有$ref引用，将子文件内容嵌入主文件，生成完整的可导入YAML。
• 导入Postman：打开Postman → 点击「Import」→ 上传生成的merged-swagger.yaml文件即可。

方法2：手动补全合并（适合小批量API） #

如果API数量不多，可手动将拆分的内容合并到主Schema中：

• 替换主Schema中paths下的$ref：将每个路径对应的子YAML内容直接粘贴到对应位置，比如把/accounts/otp的$ref: "./accounts/send_otp.yaml"替换为send_otp.yaml里的post节点内容。
• 补全definitions部分：将所有涉及的定义（如示例中的Request、Success等）合并到主Schema的definitions节点下。
• 保存为完整YAML文件后，直接导入Postman。

方法3：利用DRF原生生成完整API文档 #

由于后端基于Django Rest Framework，可直接通过框架工具生成完整的OpenAPI文档：

• 若使用drf-yasg生成Swagger文档，启动项目后访问Swagger页面（通常路径为/swagger/）。
• 在页面中找到「Download YAML」或「Download JSON」按钮，下载包含所有API和定义的完整文档。
• 将下载的文件导入Postman即可完成迁移。

内容的提问来源于stack exchange，提问作者Amin Malek Mohammadi