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，团队成员或外部开发者可直接访问最新文档。

导出集合为 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等格式直接导出，具体以你所使用的版本界面为准。

安装 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 文档，用于流水线产物归档与发布。