创建 API 文档

为源代码存储库创建 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。