在 Linux 上使用 Postman 生成接口文档
一 安装与准备
- 在 Linux 上安装 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 文档,适合对样式与静态站点有定制需求的团队。