创建 API 文档
记录源代码存储库的 API 对于为开发人员维护和使用 API 提供清晰、可访问性和易用性至关重要。 综合文档是了解 API 终结点的功能、输入、输出和使用情况的指南。 记录 API 时，应选择最合适的呈现格式（如 OpenAPI 规范或 Markdown），包括示例和用法方案，使其保持 up-to日期，并更改代码，并征求 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 文档。 这可确保文档保持 up-to日期，并反映 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。