建立 API 檔

為您的原始程式碼儲存庫建立 API 文件非常重要。 良好的文件可協助開發人員輕鬆理解、維護和使用您的 API。 完整的文件說明了 API 的工作原理、它需要什麼輸入、它給出什麼輸出以及如何使用 API 端點。 在建立API文件時，應選擇最佳格式（如OpenAPI規範或Markdown），包含範例和使用場景，在程式碼變更時保持更新，並徵求API使用者回饋以使其變得更好。 雖然 API 檔的一般方法適用於任何地方，但 Azure DevOps 與 GitHub 之間有一些差異。

在 Azure DevOps 中建立 API 檔

若要有效率地將 API 檔新增至 Azure DevOps 專案，您應該使用與開發工作流程搭配使用的專用檔工具。 流行的選擇包括 Swagger （OpenAPI）、API Blueprint 和基於 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。