在Linux系统上使用Postman生成API文档的完整步骤
1. 准备工作：安装Postman客户端
在Linux系统（如Ubuntu、CentOS）上，可通过以下方式安装Postman：
- Snap包安装（推荐）：打开终端，运行
sudo snap install postman，等待安装完成后，通过postman命令启动应用。
- AppImage安装：从Postman官网下载AppImage文件，赋予执行权限（
chmod +x Postman-linux-x64.AppImage），双击运行即可。
2. 创建API集合（Collection）
集合是Postman组织API请求的核心工具，便于统一管理文档：
- 打开Postman，点击左侧导航栏Collections（集合）旁的“+”号，选择“Create Collection”。
- 输入集合名称（如“User API Docs”）、描述（可选，说明集合功能范围），点击“Create”完成创建。
3. 添加API请求并完善信息
将需要文档化的API接口添加到集合中，并补充详细信息：
- 点击集合右侧的“+”号，选择“Add Request”。
- 输入请求名称（如“Get User Info”）、HTTP方法（GET/POST/PUT/DELETE等）、URL（如
https://api.example.com/users/{id}）。
- 切换至Headers（请求头）选项卡，添加必要参数（如
Authorization: Bearer <token>、Content-Type: application/json）。
- 切换至Params（参数）选项卡（适用于URL参数），输入参数键值对（如
id: 123）。
- 切换至Body（请求体）选项卡（适用于POST/PUT请求），选择数据格式（如
raw→JSON），输入请求体（如{"name": "John", "age": 30}）。
- 切换至Description（描述）选项卡，详细描述接口功能、参数说明、响应格式（如“返回用户基本信息，包含id、name、email”）及示例。
4. 生成并预览API文档
通过Postman内置功能快速生成在线文档：
- 在集合详情页面，点击顶部More Actions（更多操作，三个点图标），选择“View in Web”（在线预览）。
- 系统将自动打开浏览器，展示该集合的API文档页面，包含所有请求的URL、方法、参数、描述、示例响应等内容，可直接查看效果。
5. 发布API文档到互联网
若需团队外部访问，可将文档发布至Postman公共平台：
- 在集合详情页面，点击More Actions→“Publish Docs”。
- 选择文档格式（如Markdown、HTML），配置发布选项（如是否包含示例、描述）。
- 点击“Publish”，Postman将生成一个公共URL（如
https://documenter.getpostman.com/view/1234567/your-collection），分享该链接即可让他人在线查看文档。
6. 导出API文档为本地文件
若需离线保存或分享给未使用Postman的成员，可导出为Markdown、HTML等格式：
- 在集合详情页面，点击Export（导出）按钮。
- 选择导出格式（如Markdown、HTML），勾选“Include Examples”（包含示例）、“Include Description”（包含描述）选项，确保文档完整性。
- 点击“Export”，选择保存路径（如
~/Downloads），即可下载生成的文档文件。
7. 可选：使用第三方工具生成文档
若需更灵活的文档格式（如HTML），可使用第三方工具（如docgen）：
- 安装docgen：在终端运行
wget https://raw.githubusercontent.com/thedevsaddam/docgen/v3/install.sh -o install.sh && sudo chmod +x install.sh && sudo ./install.sh && rm install.sh，完成安装。
- 导出Postman集合：在Postman中选择集合，点击“Export”，选择“Collection v2.1”格式，保存为JSON文件（如
~/Downloads/api_collection.json）。
- 生成HTML文档：运行
docgen build -i ~/Downloads/api_collection.json -o ~/Downloads/api_docs.html -m，生成本地Markdown文件；或运行docgen server -f ~/Downloads/api_collection.json -p 8000，启动实时在线文档服务器（访问http://localhost:8000查看）。
注意事项
- 确保Postman版本为最新（可通过
Help→Check for Updates更新），避免因版本问题导致功能缺失。
- 导出文档时，务必勾选“Include Examples”和“Include Description”，否则文档将缺少关键信息。
- 发布文档时，注意保护敏感信息（如API密钥、密码），避免泄露。