在我之前的文章“文件即程式碼：技術作家的最佳指南”中，我討論了“文件即程式碼”的概念並對其進行了深入探討。
在開始擔任文件工程師之前，我對 API 文件了解不多。公司給我的帶回家的任務是記錄給我的 API 的端點。我經歷了這段旅程並開始學習 API 文件以及用於記錄 API 的不同工具。
我將分享迄今為止我所學到的一切。
為什麼需要 API 文件？
API（應用程式介面）在支援軟體系統有效通訊和互動方面發揮重要作用。開發人員（或任何會遇到該文件的人）需要適當的 API 文件來理解和使用這些 API。
已成為郵差最喜歡的工具之一。
-
什麼是Postman API文件？
Postman 是一個 API 開發協作平台。它簡化了建立 API 的每個步驟並簡化了協作，以便您可以更快地建立更好的 API。
為什麼應該使用 Postman 來取得 API 文件？
-
使用者友善的介面： Postman 直覺的介面使各種技能水平的開發人員都可以輕鬆建立、測試和記錄 API。
-
全面的功能：從自動化測試到監控和協作，Postman 提供了廣泛的功能來增強 API 開發流程。
-
協作工具：團隊可以共享集合、環境和文件，從而促進更好的協作和一致性。
-
如何為 API 文件設定 Postman
要開始使用 Postman，您需要在電腦上安裝應用程式。 Postman 適用於 Windows、macOS 和 Linux。您可以從Postman 網站下載它。
安裝 Postman 以取得 API 文件的步驟
-
下載 Postman：造訪 Postman 網站並下載適合您的作業系統的版本。
-
安裝 Postman：請按照特定於您的作業系統的安裝說明進行操作。
-
註冊/登入：安裝後，開啟 Postman 並註冊新帳戶或登入（如果您已有帳戶）。
-
在Postman中建立API文件的步驟
在 Postman 中建立 API 文件涉及一系列明確定義的步驟。您可以這樣做：
Postman 中的集合是什麼？
Postman 中的集合是一組請求。
第 1 步：在 Postman 中建立集合
建立集合：
-
按一下側邊欄中的「集合」標籤。
-
點選“新集合”按鈕。
-
為您的收藏命名並根據需要加入描述。
步驟 2：將請求新增至 Postman 中的收藏中
在您的集合中，您可以新增單獨的 API 請求：
-
點擊您的收藏將其打開。
-
點擊新增請求。
-
為您的請求命名並指定 HTTP 方法（GET、POST、PUT、DELETE 等）。
-
輸入 API 端點 URL 和任何必要的參數。
第 3 步：記錄每個請求
對於每個請求，您可以新增詳細文件：
-
單擊請求將其打開。
-
按一下“文件”標籤。
-
新增描述，包括有關端點、參數、標頭和範例回應的詳細資訊。
-
儲存您的變更。
第 4 步：在 Postman 中產生並檢視文件
-
去你的收藏吧。
-
點擊您的收藏旁邊的
...（三個點）選單。 -
選擇
View Documentation。這將開啟文件視圖
在郵差內。
對於可共享的網頁版本，您需要發布文件。
-
Postman 中 API 文件的 3 個重要技巧
組織 API 文件是最好的選擇。這將有助於清晰度和可用性。值得慶幸的是，Postman 提供了幾個功能來幫助您保持文件結構良好：
在 Postman 中使用資料夾
資料夾可讓您將相關請求分組到一個集合中。建立資料夾：
-
右鍵單擊您的收藏。
-
選擇新增資料夾。
-
命名您的資料夾並向其中新增請求。
Postman 中的使用環境
環境使您能夠管理不同的變數集。例如，您可能有不同的開發、暫存和生產環境。建立環境：
-
按一下側邊欄中的“環境”標籤。
-
按一下“新增” 。
-
定義變數並保護環境。
在 Postman 中使用變數
變數可用於儲存 URL、令牌或任何其他可能變更的資料等值。這使得您的請求可重複使用且更易於管理。使用變數：
-
在環境中定義它們。
-
使用
{{variable_name}}語法在您的請求中引用它們。 -
如何在Postman中共享和協作API文件
Postman 擅長實現團隊協作。以下是您可以共用和協作處理 API 文件的一些方法：
分享收藏
您可以與您的團隊共享收藏：
-
點擊您的收藏。
-
點選共享按鈕。
-
選擇您想要的分享方式（透過連結、在團隊工作區等）。
使用團隊工作空間
團隊工作區允許多個使用者即時協作。若要建立團隊工作區：
-
點選左上角的工作區名稱。
-
選擇建立工作區。
-
邀請您的團隊成員。
Postman 中的評論和版本控制
Postman 支援對請求進行評論並追蹤更改，確保每個人都保持在同一頁上。
-
Postman 中 API 文件的 5 個最佳實踐
要充分利用 Postman 來記錄 API 文件，請考慮以下最佳實踐：
清晰簡潔
確保您的文件易於理解。使用清晰的語言並避免不必要的行話。
包括範例
提供請求和回應範例，幫助使用者了解如何使用 API。
保持最新狀態
定期更新您的文件以反映 API 中的任何變更。
使用描述性名稱
描述性地命名您的集合、請求和變數，以便其他人更容易理解其用途。
利用郵差功能
利用 Postman 的功能（例如模擬伺服器、監視器和自動化測試）來增強您的 API 文件。
七、結論
總之，Postman 是一個非常強大的 API 文件工具。其用戶友好的介面、全面的功能和強大的協作工具使其成為開發人員和團隊的理想選擇。透過遵循本指南中概述的步驟和最佳實踐，您可以建立清晰、簡潔且有效的 API 文件，這將使您的 API 使用者受益匪淺。
無論您是獨立開發人員還是大型團隊的一員，利用 Postman 編寫 API 文件都可以簡化您的開發流程並提高 API 的整體品質。
讓我們在LinkedIn上聯絡吧！ ❤
原文出處：https://dev.to/dumebii/using-postman-for-api-documentation-all-you-need-to-know-2ap9
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式