Ubuntu中Postman生成接口文档的详细步骤
1. 准备工作：创建接口集合
接口集合（Collection）是Postman组织API请求的核心容器，便于批量管理和文档生成。
- 打开Postman应用，点击左侧导航栏的“Collections”选项卡。
- 点击右上角的“+”按钮，选择“Collection”，输入集合名称（如“电商API”）、描述（如“电商平台接口集合”），点击“Create”完成创建。
2. 添加API请求到集合
将需要生成文档的API请求逐一添加到集合中，并完善请求细节。
- 在集合内点击右上角的“+”按钮，选择“Request”。
- 输入请求名称（如“获取商品列表”）、URL（如“https://api.ecommerce.com/products”）、HTTP方法（如GET）。
- 在“Params”选项卡中添加路径/查询参数（如“category=electronics”），在“Headers”选项卡中添加请求头（如“Authorization: Bearer xxx”），对于POST/PUT请求，在“Body”选项卡中选择“raw”格式并输入JSON请求体（如
{"username": "testuser", "password": "testpass"}）。 - 点击“Save”将请求保存到集合中。
3. 完善请求描述信息
为每个请求添加清晰的描述，是生成高质量文档的关键。
- 选中集合中的某个请求，切换到右侧“Description”选项卡。
- 输入请求的功能说明（如“获取指定分类的商品列表”）、参数说明（如“category：商品分类，必填，字符串”）、响应格式说明（如“返回JSON数组，包含商品ID、名称、价格”）、示例数据（如成功响应示例：
[{"id": 1, "name": "手机", "price": 2999}]，失败响应示例：{"code": 404, "message": "分类不存在"}）。 - 点击“Save”保存描述信息。
4. 生成接口文档
Postman提供两种主要的文档生成方式：在线查看/分享和本地导出。
方式一：在线生成并分享文档（推荐）
- 在集合界面，点击集合右上角的“…”按钮，选择“View in Web”。
- Postman会将集合上传至云端，生成在线文档页面，包含所有请求的URL、方法、描述、参数、示例等信息。
- 点击“Publish Docs”按钮，生成公共URL（如
https://documenter.getpostman.com/view/123456/your-collection），团队成员可通过该链接直接查看文档，无需安装Postman。
方式二：本地导出文档
- 在集合界面，点击集合右上角的“…”按钮，选择“Export”。
- 在弹出的窗口中，选择导出格式（目前Postman原生支持“Collection v2.1”/“Collection v2.0”JSON格式，此格式可直接导入Postman）。
- 勾选“Include descriptions”（包含描述）、“Include examples”（包含示例）选项，确保文档包含详细信息。
- 点击“Export”，选择保存路径（如桌面），生成JSON格式的文档文件。
5. 高级选项：使用第三方工具增强文档功能
若需要更丰富的文档格式（如Markdown、HTML）或协作功能，可使用第三方工具（如Apifox）：
- 将Postman集合导出的JSON文件导入Apifox。
- Apifox支持一键生成Markdown、HTML等格式的文档，支持在线调试、团队协作、自定义样式等功能。
- 导出后的文档可通过链接分享，或导出为Word、PDF等格式供线下使用。
