在 Ubuntu 上用 Postman 编写与发布接口文档
一 环境准备
- 安装 Postman（任选其一）
- 使用 Snap（推荐）：
- 更新系统并安装 Snap：sudo apt update && sudo apt install snapd
- 安装 Postman：sudo snap install postman --classic
- 手动安装：
- 从官网下载 Linux 64 位安装包（.tar.gz），解压至 /opt：tar -xzf Postman-linux-x64-*.tar.gz -C /opt
- 创建软链接便于启动：sudo ln -s /opt/Postman/Postman /usr/local/bin/postman
- 创建桌面快捷方式（/usr/share/applications/postman.desktop），示例：
- [Desktop Entry] Encoding=UTF-8
- Name=Postman
- Exec=/opt/Postman/Postman
- Icon=/opt/Postman/app/resources/app/assets/icon.png
- Terminal=false
- Type=Application
- Categories=Development;
- 启动与登录：在应用菜单或终端输入 postman 启动，登录或注册 Postman 账号以启用云端协作与发布能力。
二 编写接口文档的步骤
- 创建 Collection（集合）：用于组织同一项目或模块的接口，建议添加集合级 Description 概述用途、鉴权方式与全局注意事项。
- 添加 Request（请求）：在集合或文件夹下新建请求，填写 URL、Method、Headers、Body；在请求的 Description 中写清功能、权限、业务规则、注意事项等。
- 完善 参数与响应说明：
- 在请求的 Params/Headers/Body 中为字段添加描述、类型、是否必填、示例值与约束（如长度、正则）。
- 发送请求后，将响应保存为 Example（样例）：Send → Save Response → Save as example；为成功、失败、异常分别建样例，样例的 Body/Headers/Status 越真实越利于对接。
- 结构化管理：用 Folder（文件夹） 按模块/控制器拆分，保持层级清晰；为关键接口补充 前置条件 与 后置影响。
三 预览发布与分享
- 在线预览文档：在集合菜单中选择 View in Web，即可在浏览器查看包含 示例 的可读文档页面。
- 发布文档：在集合侧边或详情页使用 Publish Docs，生成 公共 URL，团队成员或外部开发者可直接访问；后续修改建议同步更新发布页以保持一致性。
- 导出与离线分享：
- 导出 Collection JSON：便于团队成员导入 Postman 复用请求与文档。
- 部分版本/方案支持导出 Markdown 文档（在导出选项中勾选 包含示例 与 包含描述），用于放入代码仓库或内网知识库；如未提供该选项，可结合导出的 Collection 与示例在外部生成文档。
四 协作与维护建议
- 使用 工作区（Workspace） 进行团队协作，按项目/环境拆分；必要时邀请成员加入工作区，统一版本与变更记录。
- 通过 环境（Environment） 管理不同环境（如 Development/Staging/Production）的变量（如 {{base_url}}、{{api_key}}），在文档与示例中引用变量，减少维护成本。
- 配置 代理（Proxy）（如公司内网需要）：Settings → General → Proxy，填写 HTTP/HTTPS 代理 与认证信息，确保请求与文档示例可达。
- 文档即代码：将导出的 Collection JSON 纳入 Git 管理，配合 变更说明 与 版本标签，实现文档与接口同步演进。
