创建 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 终结点、操作、参数、响应以及任何其他相关信息。 鉴于 Markdow 格式的广泛支持和易用性，请考虑使用此格式创建该文档。 定义各个文档的一致结构，将每个文档划分为描述身份验证、终结点、请求参数、响应示例等内容的部分。
与 Azure DevOps 一样，可以使用文档生成器或静态站点生成器来简化从 Markdown 文件生成 API 文档的过程。 热门选择包括 Jekyll、MkDocs、Docusaurus 和 Hugo。 配置生成器以分析 Markdown 文件并生成静态 HTML 页。 可以自定义布局、主题和样式，以匹配项目的品牌和首选项。
若要发布 HTML 内容，请利用 GitHub Pages，以便直接从 GitHub 存储库托管静态网站。 为此，可以创建专用分支并将 HTML 文件推送到此分支。 还可以实现 GitHub Actions，以便在文档文件或代码库发生更改时自动生成和部署 API 文档。
设置 GitHub Actions 以在文档文件或代码库发生更改时自动生成和部署 API 文档。 配置自动化工作流以使用所选文档生成器生成 HTML 文档文件，并将其部署到 GitHub Pages。