Ubuntu 下 Postman 生成 API 文档的实用方法
一 在线预览与发布文档
- 在 Postman 中选中目标集合 Collection，点击右侧的View in Web在线预览文档；如需对外公开，进入Publish Docs并点击Publish，系统会生成Public URL，团队成员或外部开发者可直接访问。发布后的文档会自动同步更新，无需重复发布。此方式适合快速分享与对外展示。
二 导出为 Markdown 或 HTML 文件
- 在集合的详情页或集合右侧菜单中选择导出 Export，导出为JSON 集合文件；随后使用开源工具docgen将集合转换为Markdown/HTML文档：
- 安装 docgen（示例）：go install github.com/thedevsaddam/docgen@latest
- 启动本地预览：docgen server -f postman_collection.json -p 8000（浏览器访问 http://localhost:8000）
- 生成 HTML：docgen build -i postman_collection.json -o ~/Downloads/index.html
- 生成 Markdown：docgen build -i postman_collection.json -o ~/Downloads/index.md -m
该方式便于纳入Git仓库、配合CI/CD自动生成站点或静态文件发布。
三 在 Ubuntu 上安装与运行 Postman
- 下载 Linux 版 Postman 安装包（.tar.gz），解压并移动到**/opt**：tar -xvf Postman-linux-x64-.tar.gz && sudo mv Postman /opt/Postman
- 创建符号链接便于启动：sudo ln -s /opt/Postman/Postman /usr/bin/postman
- 之后可直接运行命令：postman 打开桌面应用，按上文步骤生成与发布文档。
四 提升文档质量的实用建议
- 为每个接口补充请求/响应示例（成功、失败、异常），并在示例中展示状态码、响应结构与错误码说明，便于消费方对接与联调。
- 统一参数说明（路径、查询、请求头、请求体），为字段添加类型、是否必填、取值范围与示例值，减少沟通成本。
- 使用环境变量管理Base URL与鉴权 Token，在文档中清晰标注变量的作用域与获取方式，避免把敏感信息写死在示例里。
- 若采用导出 JSON方式分发，建议在导出前清理历史记录/缓存，避免团队成员导入到旧版本；同时保留一份变更说明或版本标签，便于追溯。
