Linux Postman如何生成文档

本文介绍如何在Linux系统中利用postman高效生成API文档。 我们将涵盖使用Postman界面和命令行工具两种方法。

一、 使用Postman界面生成API文档

首先，需要在Postman中做好准备工作：

1. 创建并组织API请求集合: 创建一个新的集合，并添加所有API请求。 为每个请求添加详细描述，包括功能、参数、请求头、请求体以及预期响应。 最好提供成功、失败和异常情况的示例响应。

2. 预览和发布文档: 在集合视图中，点击“View in Web”即可在浏览器中预览生成的文档。 点击“Publish Docs”则可以生成一个公开的URL，方便团队成员或其他开发者访问。

二、 使用第三方工具导出为html或Markdown

Postman自身不直接支持将集合导出为HTML或Markdown。 推荐使用docgen工具。

1. 安装docgen: 使用以下命令安装：

wget https://raw.githubusercontent.com/thedevsaddam/docgen/v3/install.sh -o install.sh && sudo chmod +x install.sh && sudo ./install.sh && rm install.sh

2. 导出Postman集合为JSON: 从Postman导出你的API集合为json文件（例如，~/Downloads/my_api.json）。

3. 使用docgen转换:

• 在线预览HTML文档:

  docgen server -f ~/Downloads/my_api.json -p 8000

• 生成本地HTML文档:

  docgen build -i ~/Downloads/my_api.json -o ~/Downloads/my_api.html

• 生成本地Markdown文档:

  docgen build -i ~/Downloads/my_api.json -o ~/Downloads/my_api.md -m

三、 使用Postman命令行工具 (newman)

Postman的命令行工具newman提供更强大的文档生成和管理能力。

1. 安装Postman CLI:

sudo apt-get install libgconf-2-4 wget https://dl.pstmn.io/download/latest/Linux64 -O postman.tar.gz sudo tar -xzf postman.tar.gz -C /opt sudo ln -s /opt/Postman/Postman /usr/bin/postman

2. 使用newman生成文档: 假设你的集合文件为/path/to/my_api.json，环境文件为/path/to/my_environment.json，则使用以下命令生成HTML文档：

newman run /path/to/my_api.json -e /path/to/my_environment.json -o /path/to/output.html

通过以上方法，您可以轻松地在Linux系统中生成和管理API文档，提高API的可读性、可维护性和团队协作效率。 选择最适合您工作流程的方法即可。