建立 API 文件
記錄原始程式碼存放庫的 API 對於為開發人員維護及取用 API 提供明確性、可使用性及易於使用性至關重要。 完整的文件可作為了解 API 端點功能、輸入、輸出和使用方式的指南。 記錄 API 時，您應該選取最適合的簡報格式 (例如 OpenAPI 規格或 Markdown)，包括範例和使用案例、保持程式碼變更的最新狀態，以及向 API 取用者徵求意見反應，以持續改善其品質。
雖然記錄 API 的一般方法與平台無關，但其實作在 Azure DevOps 與 GitHub 之間有一些差異。
在 Azure DevOps 中記錄 API
若要以最有效率的方式將 API 文件新增至 Azure DevOps 專案，您應該考慮使用與開發工作流程整合的專用文件工具或平台。 此類別的熱門選擇包括 Swagger (OpenAPI)、API 藍圖和 Markdown 型文件系統，例如 MkDocs 或 Docusaurus。 其 Azure DevOps 整合功能可協助自動化產生文件的程序，使其與程式碼基底保持同步。 大部分的文件工具也支援剖析內嵌註解，並將其包含在自動產生的文件中。
您應該將 API 文件發佈至可供小組成員和專案關係人存取的中央位置。 這可能是專用的文件網站、Azure DevOps 內的 Wiki 或外部文件入口網站。
或者，您可以直接在程式碼內使用程式碼註解或裝飾項目，以新增描述其 API 端點的中繼資料。 Swagger Codegen 或 Springfox 等工具能夠處理這些註解並產生 OpenAPI 規格檔案。
設定 Azure Pipelines 內的自動化程序，以在程式碼基底變更時自動產生 API 文件。 這可確保您的文件保持最新狀態，並反映 API 中的最新變更。
在 Github 中記錄 API
使用 GitHub 時，請考慮利用屬於 GitHub 生態系統一部分的工具來產生 API 文件。
首先，記錄 API 端點、作業、參數、回應，以及任何其他相關資訊。 請考慮以 Markdown 格式建立該文件，以考慮其廣泛的支援和易於使用。 定義個別文件的一致結構，將每個文件分割成描述驗證、端點、要求參數、回應範例等區段。
如同 Azure DevOps，您可以使用文件產生器或靜態網站產生器，以簡化從 Markdown 檔案產生 API 文件的程序。 熱門選擇包括 Jekyll、MkDocs、Docusaurus 和 Hugo。 設定產生器來剖析 Markdown 檔案並產生靜態 HTML 頁面。 您可以自訂版面配置、主題和樣式，以符合專案的商標和喜好設定。
若要發佈 HTML 內容，請利用 GitHub Pages，讓您直接從 GitHub 存放庫裝載靜態網站。 您可以為此建立專用分支，並將 HTML 檔案推送至此分支。 您也可以實作 GitHub Actions，以在文件檔案或程式碼基底變更時自動建置和部署 API 文件。
設定 GitHub Actions，以在文件檔案或程式碼基底變更時自動建置和部署您的 API 文件。 設定自動化工作流程，以使用所選的文件產生器產生 HTML 文件檔案，並將其部署至 GitHub Pages。