本文介紹如何在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的可讀性、可維護性和團隊協作效率。 選擇最適合您工作流程的方法即可。