CentOS 下使用 Postman 生成接口文档
一 环境准备
- 在 CentOS 上安装 Postman（Linux 版）：
- 从官网下载 Postman-linux-x64-xx.xx.xx.tar.gz；
- 解压到目标目录：tar -xvf Postman-linux-x64-xx.xx.xx.tar.gz -C /opt；
- 建立软链便于启动：sudo ln -s /opt/Postman/Postman /usr/local/bin/postman；
- 运行 postman 启动桌面应用。以上步骤完成后即可在 CentOS 桌面环境使用 Postman 进行文档生成与发布。
二 在 Postman 中准备集合与示例
- 创建 Collection 并添加接口请求，为每个请求补充：
- 请求目的、业务场景的描述；
- Params / Headers / Body 的参数名、类型、是否必填、示例与说明；
- 为每个接口准备多套 Examples（成功、失败、异常），可直接在发送请求后将 Response 保存为示例，提升文档可读性与可测性。
三 生成与发布文档
- 在线预览与发布：在集合菜单中选择 View in Web 在线预览文档；需要对外共享时，使用 Publish Docs 生成可公开访问的链接，发布后可在 Postman 提供的托管域名查看，后续更新会同步到已发布页面。
- 导出离线文档：在集合详情页选择 导出，常用格式为 Markdown；导出时勾选 包含示例 与 包含描述，便于团队离线查看与版本归档。
- 分享与协作：导出的 Markdown/JSON 可通过邮件、代码仓库或协作平台共享；他人可直接导入 Collection JSON 到 Postman 复现请求与示例。
四 进阶 生成 Mock 服务与规范导出
- 基于已完善的 Examples 一键创建 Mock Server，用于前后端并行开发或联调前的接口仿真，降低依赖风险。
- 如需对接外部规范生态，可在 Postman 中导出或维护 OpenAPI 规范，再配合 Swagger UI / Redoc 等工具渲染交互式文档，满足标准化与多端展示需求。
五 常见问题与实用建议
- 文档更新后未同步到线上：发布后再次点击 Publish Docs 更新线上页面，确保团队成员看到最新内容。
- 示例不直观：务必为每个接口补齐 成功/失败/异常 示例，并在示例说明中标注前置条件、权限与返回码含义。
- 离线归档与审阅：优先导出 Markdown 并纳入代码仓库，便于 Review 与历史版本对比；二进制 JSON 适合直接导入 Postman 复现请求。
- 编辑稳定性：在需要撰写较多说明时，可切换为 Classic Markdown editor 以避免富文本编辑器的潜在稳定性问题。
