本文介绍如何在Linux系统中利用Postman高效生成API文档。 我们将涵盖使用Postman界面和命令行工具两种方法。
一、 使用Postman界面生成API文档
首先，需要在Postman中做好准备工作：
-
创建并组织API请求集合: 创建一个新的集合，并添加所有API请求。 为每个请求添加详细描述，包括功能、参数、请求头、请求体以及预期响应。 最好提供成功、失败和异常情况的示例响应。
-
预览和发布文档: 在集合视图中，点击“View in Web”即可在浏览器中预览生成的文档。 点击“Publish Docs”则可以生成一个公开的URL，方便团队成员或其他开发者访问。
二、 使用第三方工具导出为HTML或Markdown
Postman自身不直接支持将集合导出为HTML或Markdown。 推荐使用docgen工具。
- 安装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
-
导出Postman集合为JSON: 从Postman导出你的API集合为JSON文件（例如，
~/Downloads/my_api.json）。
拍拍客 免费易推广api系统下载这是一套由淘掌门(taozhangmen.net)衍生出来的一个拍拍客系统！这套程序也继承了淘掌门的特点：永久免费开源！无任何时间限制、功能限制、域名限制。 程序相对于淘掌门原型，已去除返利、会员系统、文章系统等。 如果需要文章，可单独下载其他的文章系统，做子目录，效果可能会更好。 程序安装过程与淘掌门相同： 下载上传到空间，执行 你的网址/install.php 安装完成后，登陆后台修改拍拍AP
-
使用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提供更强大的文档生成和管理能力。
- 安装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
-
使用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的可读性、可维护性和团队协作效率。 选择最适合您工作流程的方法即可。
