Linux Postman如何生成文档 - 问答

在Linux系统下使用Postman生成API文档，可以按照以下步骤进行：

1. 创建和整理API请求

创建接口集合：在Postman中创建一个接口集合，描述该接口集合的功能和范围等信息。
添加接口：将所有需求已清晰的接口定义到集合当中。
描述接口：为每个接口添加描述信息，包括接口的作用、参数、请求头和请求体等。
生成样例：为接口生成成功样例、失败样例和异常样例，以便展示接口的不同执行结果。

2. 预览和发布API文档

预览文档：在集合的选项中，点击“View in Web”，即可在浏览器中预览创建的文档和示例。
发布文档：如果想让其他人能看到这个文档，可以点击“Publish Docs”，生成一个公开的网页链接（Public URL），所有人都可以查看。

3. 使用第三方工具导出为HTML或Markdown

Postman本身不直接支持将JSON转换为HTML或Markdown，但你可以使用第三方工具如docgen来实现这一功能。

安装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

转换JSON为HTML和Markdown

# 从Postman导出为JSON文件
docgen server -f ~/Downloads/Api_Test_postman_collection.json -p 8000

# 查看实时在线HTML文档
docgen server -f ~/Downloads/Api_Test_postman_collection.json -p 8000

# 生成本地HTML文档
docgen build -i ~/Downloads/Api_Test_postman_collection.json -o ~/Downloads/Api_Test_postman_collection.html

# 生成本地Markdown文档
docgen build -i ~/Downloads/Api_Test_postman_collection.json -o ~/Downloads/Api_Test_postman_collection.md -m

4. 使用Postman命令行工具

如果你更喜欢使用命令行，可以安装Postman命令行工具，然后使用newman来生成和发布文档。

安装Postman命令行工具

# 安装必要的依赖
sudo apt-get install libgconf-2-4

# 下载Postman CLI工具
wget https://dl.pstmn.io/download/latest/linux64 -O postman.tar.gz

# 解压到/opt目录
sudo tar -xzf postman.tar.gz -C /opt

# 创建软链接
sudo ln -s /opt/Postman/Postman /usr/bin/postman

生成和发布文档

# 使用newman生成HTML文档
newman run /path/to/postman_collection.json -e /path/to/postman_environment.json -o /path/to/output.html

通过以上步骤，你可以在Linux系统下使用Postman生成和管理API文档，从而提高API的可读性和可维护性，促进团队间的协作和沟通。

0 赞

0 踩