Postman在Ubuntu上如何进行API文档生成

在Ubuntu上使用Postman生成API文档的步骤

1. 安装Postman（若未安装）

Postman支持多种方式在Ubuntu上安装，常见方法如下：

• Snap包管理器：打开终端，依次执行sudo snap install core（添加Snap商店密钥）、sudo snap install postman --classic（安装Postman）。
• APT包管理器：导入Postman GPG密钥（wget -qO - https://dl.postman.co/postman.gpg | sudo apt-key add -），添加APT仓库（sudo sh -c 'echo "deb https://dl.postman.co/debian $(lsb_release -cs) main" > /etc/apt/sources.list.d/postman.list'），更新包列表（sudo apt update）并安装（sudo apt install postman）。
• Flatpak：安装Flatpak（sudo apt install flatpak），添加Flathub仓库（flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo），安装Postman（flatpak install flathub com.postman.Postman）。

2. 创建并组织API集合

打开Postman应用，点击左侧边栏“新建”按钮，选择“Collection”创建新集合（如命名为“User API”）。集合是组织API请求的核心单元，可将同一项目的接口归类管理。创建后，可为集合添加描述（如“用户管理模块接口集合”），便于后续识别。

3. 添加API请求并完善描述

在集合内点击“Add Request”（或右键选择“Add Request”）创建新请求。填写请求详情：

• 基础信息：输入API URL（如https://api.example.com/users）、HTTP方法（GET/POST/PUT等）；
• 请求头/体：添加必要的请求头（如Content-Type: application/json）或请求体（如JSON格式的参数{"name": "John", "age": 30}）；
• 描述信息：切换至“Description”选项卡，添加请求参数说明（如“name：用户姓名，必填，字符串类型”）、响应格式（如“返回用户ID和姓名”）及示例（如成功响应{"id": 1, "name": "John"}）。

4. 生成并自定义API文档

方法一：通过Postman内置功能生成

• 在左侧边栏选中目标集合，点击右上角“…”（更多操作），选择“View in Documentation”（查看文档）。Postman会根据集合中的请求自动生成Markdown格式的文档，包含请求方法、URL、参数、描述及示例。
• 若需导出文档，可在文档页面点击“Export”（导出），选择格式（如Markdown、HTML），保存至本地。

方法二：发布文档至云端共享

• 在集合右上角点击“Publish Docs”（发布文档），输入文档名称、描述（如“用户API正式版文档”），选择权限（公开/私有），点击“Publish”（发布）。发布后，Postman会生成一个公共URL（如https://documenter.getpostman.com/view/1234567/User-API/67890），团队成员可通过该链接在线查看文档。

5. 可选：使用第三方工具增强文档功能

若需要更丰富的文档格式或自动化功能，可使用第三方工具：

• Docodile：从Postman集合导出JSON文件，通过Docodile生成HTML格式的API文档，支持自定义样式；
• ApiPost：支持团队协作编辑，直接生成并导出Markdown、HTML文档，可与Postman集合同步。