Postman在Ubuntu如何生成文档

在 Ubuntu 上可用三种常见方式生成 Postman 接口文档：在线发布、导出文件、CI/CD 自动化生成。下面给出可直接执行的步骤与命令。

安装与准备

• 安装 Postman（任选其一）
  • Snap：sudo snap install postman --classic
  • APT：导入 GPG 并添加仓库后安装
    • wget -qO - https://dl.postman.co/postman.gpg | sudo apt-key add -
    • echo “deb https://dl.postman.co/debian $(lsb_release -cs) main” | sudo tee /etc/apt/sources.list.d/postman.list
    • sudo apt update && sudo apt install postman
  • Flatpak：flatpak install flathub com.postman.Postman
• 在 Postman 中创建集合（Collection），添加请求（Request），并在请求的 Description / Params / Headers / Body 中完善说明；发送请求后将响应保存为成功/失败/异常示例，便于生成更完整的文档。

方式一 在线预览与发布文档

• 在线预览：在左侧选中目标集合，点击右侧**“⋮”或右上角“View in Web”，打开 Web 版 Postman 的Documentation**页面，可实时查看接口方法、URL、参数、示例等。
• 发布文档：在集合详情页点击**“Publish Docs / Publish Collection”，选择公开/私有与工作空间**，发布后会生成公共 URL，团队成员或外部开发者可直接访问最新文档。

方式二 导出为 Markdown HTML 或 OpenAPI

• 导出集合为 JSON：在集合右侧**“⋮” → Export**，选择Collection Format v2.1，勾选Include Examples / Include Description，保存为 .json 文件，便于共享与版本管理。
• 生成 Markdown/HTML（离线）
  • 安装 docgen（Postman 集合文档生成工具）：
    • wget https://raw.githubusercontent.com/thedevsaddam/docgen/v3/install.sh -O install.sh && sudo chmod +x install.sh && sudo ./install.sh && rm install.sh
  • 生成文档：
    • HTML：docgen build -i ~/Downloads/your-collection.json -o ~/Downloads/your-collection.html
    • Markdown：docgen build -i ~/Downloads/your-collection.json -o ~/Downloads/your-collection.md -m
• 说明：部分版本的 Postman 也支持在界面中选择Markdown/HTML/OpenAPI JSON等格式直接导出，具体以你所使用的版本界面为准。

方式三 CI CD 自动化生成

• 安装 Newman（Postman 命令行工具）
  • 依赖：sudo apt-get install libgconf-2-4
  • 下载与安装：
    • wget https://dl.pstmn.io/download/latest/linux64 -O newman.tar.gz
    • sudo tar -xzf newman.tar.gz -C /opt
    • sudo ln -s /opt/Newman/newman /usr/bin/newman
• 生成 HTML 报告（示例）
  • newman run ~/Downloads/your-collection.json -e ~/Downloads/your-environment.json -o ~/Downloads/output.html
  • 说明：-e 为可选环境变量文件；可结合 newman-reporter-htmlextra 等报告器输出更美观的 HTML 文档，用于流水线产物归档与发布。