在 CentOS 上使用 Postman 生成接口文档
一 环境准备
- 安装 Postman（Linux 版）
- 下载安装包并解压到 /opt：
tar -xvf Postman-linux-x64-xx.xx.xx.tar.gz -C /opt
- 创建软链便于启动：
sudo ln -s /opt/Postman/Postman /usr/local/bin/postman
- 启动：
postman（首次启动按提示登录 Postman 账号）
- 建议使用 桌面环境（如 GNOME/KDE）或 X11 转发运行 Postman，以便使用图形界面完成文档编辑与发布。
二 在 Postman 内生成与发布文档
- 创建并完善集合
- 新建 Collection，按模块添加 Folder 与 Request。
- 为每个请求在 Body/Headers/Params 中填写参数说明，并在 Description 中补充业务含义、错误码等。
- 保存多个 Example（成功/失败/异常），便于生成示例丰富的文档。
- 在线预览与发布
- 在集合菜单选择 View in Web 在线预览文档与示例。
- 需要对外共享时，使用 Publish Docs 将文档发布到 Postman 提供的在线页面，便于团队或外部开发者访问与评论。
- 导出离线文档
- 在集合详情选择 Export，常用格式为 Markdown；导出时勾选 包含示例 与 包含描述，便于离线阅读与归档。
三 无头环境或自动化导出方案
- Postman 的文档生成与发布依赖图形界面，服务器无头环境（仅 CLI）下建议采用以下替代流程：
- 在本地或带界面的环境中完成集合与文档的编辑、预览与发布。
- 将集合以 Collection v2.1 格式导出（JSON），通过 Git 同步到 CentOS 服务器。
- 在服务器使用 newman（Postman 官方 CLI）运行集合并生成报告（如 HTML/JSON），用于接口回归与留痕；注意：newman 报告偏重测试结果，不等同于可视化 API 文档。
- 若需离线文档，可在本地导出 Markdown 后同步到服务器，用 Nginx 或静态站点托管，供内网查阅。
四 协作与权限设置
- 使用 工作区 进行团队协作，邀请成员后可共同维护集合与文档。
- 未添加协作者时，可通过 分享链接 进行只读访问（注意访问控制与有效期）。
五 常见问题与排查
- 无法启动 Postman：确认已安装 GNOME/KDE 或启用 X11 转发；无图形环境建议改为本地编辑后导出/发布。
- 文档缺少示例：为每个接口至少保存一个 Success Example，必要时补充 Failure/Exception Example。
- 导出内容不完整：导出 Markdown 时勾选 包含示例 与 包含描述，确保参数、响应结构与错误码说明被带入文档。