如何在Ubuntu上利用Postman进行接口文档编写

在 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 管理，配合 变更说明 与 版本标签，实现文档与接口同步演进。