如何在Linux上用Postman进行接口文档生成

在 Linux 上使用 Postman 生成接口文档

一 安装与准备

• 在 Linux 上安装 Postman（桌面版）：
  • 从官网下载 Linux 版本安装包（.tar.gz）。
  • 解压并放入系统目录：

    tar -xvf Postman-linux-x64-<version>.tar.gz -C /opt
    sudo ln -s /opt/Postman/Postman /usr/local/bin/postman
    

  • 运行 Postman：在应用菜单启动，或在终端执行 postman。
• 创建并完善 Collection：
  • 新建集合，按模块/版本组织接口。
  • 为每个请求补充 Description（功能、权限、注意事项）、Params/Headers/Body 说明，并保存成功/失败/异常的 Examples，便于生成高质量文档。

二 在 Postman 内生成与发布文档

• 在线预览文档：在集合菜单中选择 View in Web，即可查看包含示例的可读文档页面。
• 发布文档：在集合右上角点击 Publish Docs，选择展示风格与可见范围，生成 公共 URL 供团队或外部查看；后续更新集合后，发布页可同步更新。
• 导出文档：在集合详情选择 导出，常用格式为 Markdown；导出时勾选 包含示例 与 包含描述，便于离线阅读与归档。

三 团队协作与权限控制

• 创建 Postman 团队，邀请成员并设置角色权限（如查看/编辑/管理文档）。
• 通过 集合共享 与 评论 在接口层面协作，统一版本与变更记录，减少沟通成本。

四 自动化与集成方案

• 无头/CI 场景：将集合导出为 JSON 并与 Newman 结合，使用 newman run collection.json --reporter-html 生成 HTML 报告，作为静态文档归档或接入流水线。
• 第三方工具链：将 Postman Collection 作为输入，使用如 Docodile 等工具生成 HTML 文档，适合对样式与静态站点有定制需求的团队。