如何编写 API 文档：最佳实践和示例

如果构建 API，则必须记录它们。为了让用户能够使用 API，必须知道如何使用它。作为一位撰写了大量文档的作者，常用的一句话是：“如果没有记录，它就不存在”——用户只有在能够发现其存在并了解如何使用时，才能真正使用某项功能。

那么，什么是 API 文档？应该如何编写？应该包含哪些内容？最佳实践是什么？本文将回答这些问题，并提供一些创建 API 文档的最佳实践。

什么是 API 文档？

API 文档是用户用来学习如何有效地使用 API 构建应用程序的资料集合。它应包括以下内容：

端点、参数、请求和响应对象以及预期状态代码的 API 参考文档
使用 API 的示例
请求和响应对象的示例，帮助用户了解需要传递的内容和预期返回的内容
可以返回的错误消息和状态代码及其含义
基本使用指南，如如何开始、进行身份验证和常见使用场景
针对更复杂方案的教程

为什么 API 文档很重要？

API 文档是用户了解如何使用 API 的重要途径。如果没有文档，用户可能很难使用 API，甚至不知道从哪里开始。缺乏文档会导致 API 难以发现——没有任何类型的文档，用户实际上无法知道要调用哪些端点。即使有端点列表，用户仍需要知道如何传递数据以及期望的返回结果。

文档不仅展示了 API 的功能，还提供了如何有效使用 API 的详细信息。这可能包括正确的身份验证方法、如何处理错误以及使用 API 的最佳实践。

例如，如果调用某个终结点来检索数据时返回 404 状态代码，这是否意味着数据不存在，还是表示没有访问权限？良好的文档将对此进行解释，并提供处理此情况所需的信息。

如何及在哪里编写 API 文档？

编写 API 文档的最佳位置就是在 API 内部！

API 规格

发布 API 时，应始终附带 API 规范。这些生成的文档列出了 API 端点以及请求和响应对象，并采用 Swagger 或 OpenAPI 等标准。最大优点是许多情况下可以自动生成！例如，使用 FastAPI（一个用于构建 API 的 Python 框架）时，可以让框架自动创建 OpenAPI 规范，无需额外编写代码。

API 规范默认提供端点列表、端点参数的预期内容以及请求和响应对象。这些通常是 JSON 或 YAML 文档，初始状态下不易阅读，但许多工具可以将其转换为美观的托管文档（例如，FastAPI 内置了这一功能），并可集成到 API 工具或托管流程中。

向 API 规范添加文档

除了列出端点的规范外，还可以包含各种文档内容，包括：

顶级 API 文档，详细描述 API 使用方法、身份验证过程和最佳实践
端点描述
端点参数的描述和示例
请求和响应对象的描述和示例
不同状态代码的描述，包括可能返回这些状态代码的原因及附带的数据

例如，llama store 在 OpenAPI 规范中提供了一个顶级描述：

{

  "openapi": "3.1.0",

  "info": {

    "title": "Llama Store API",

    "description": "The llama store API! Get details on all your favorite llamas.\n\n## To use this API\n\n- You will need to register a user, once done you can request an API token.\n- You can then use your API token to get details about the llamas.\n\n## User registration\n\nTo register a user, send a POST request to `/user` with the following body:\n    \n```json\n{\n    \"email\": \"<your email>\",\n    \"password\": \"<your password>\"\n}\n```\nThis API has a maximum of 1000 current users. Once this is exceeded, older users will be deleted. If your user is deleted, you will need to register again.\n## Get an API token\n\nTo get an API token, send a POST request to `/token` with the following body:\n    \n```json\n{\n    \"email\": \"<your email>\",\n    \"password\": \"<your password>\"\n}\n```\n\nThis will return a token that you can use to authenticate with the API:\n\n```json\n{\n  \"access_token\": \"<your new token>\",\n  \"token_type\": \"bearer\"\n}\n```\n\n## Use the API token\n\nTo use the API token, add it to the `Authorization` header of your request:\n\n```\nAuthorization: Bearer <your token>\n```\n\n\n"

  }

}

在代码中设置时，FastAPI 支持将这些类型的 OpenAPI 值添加到 API 代码中：

app = FastAPI(

    servers=[{"url": "http://localhost:8000", "description": "Prod"}],

    contact={"name": "liblab", "url": "https://liblab.com"},

    description="The llama store API! Get details on all your favorite llamas.\n\n## To use this API\n\n- You will need to register a user, once done you can request an API token.\n- You can then use your API token to get details about the llamas.\n\n## User registration\n\nTo register a user, send a POST request to `/user` with the following body:\n    \n```json\n{\n    \"email\": \"<your email>\",\n    \"password\": \"<your password>\"\n}\n```\nThis API has a maximum of 1000 current users. Once this is exceeded, older users will be deleted. If your user is deleted, you will need to register again.\n## Get an API token\n\nTo get an API token, send a POST request to `/token` with the following body:\n    \n```json\n{\n    \"email\": \"<your email>\",\n    \"password\": \"<your password>\",\n}\n```\n\nThis will return a token that you can use to authenticate with the API:\n\n```json\n{\n  \"access_token\": \"<your new token>\",\n  \"token_type\": \"bearer\"\n}\n```\n\n## Use the API token\n\nTo use the API token, add it to the `Authorization` header of your request:\n\n```\nAuthorization: Bearer <your token>\n```\n\n\n",

    openapi_tags=tags_metadata,

    version="0.0.1",

    redirect_slashes=True,

    title="Llama Store API",

)

注意到描述中使用了 markdown，这在文档中表现良好。这是为 API 规范添加丰富文档、教程和最佳实践的有效方法。这种丰富的文档可以包含代码示例、错误消息等。

生成的文档不仅应通过 API 提供，还应托管在公共文档站点上。

其他文档

除了在 API 规范中记录 API 外，还可以在公共文档站点上添加其他文档。API 规范文档将作为参考资料，但还应包括教程、操作指南和最佳实践文档。

API 规范文档可以定义每个端点的作用以及如何调用它，但可能无法描述用户在典型任务中应采取的正确流程。例如，如果 API 包含长时间运行的任务，则需要记录如何触发任务、检查状态以及检索结果，这些操作可能涉及不同的端点。

谁应该编写 API 文档？

作为从工程工作转向开发者关系的人，编写文档的挑战显而易见。虽然这不是大多数工程师的强项或偏好，但它却是不可或缺的任务。

理想情况下，文档应由专门的技术作家编写，他们会与工程师合作了解 API 的工作原理，并与产品团队协作理解用户体验。这些文档应反馈给工程师，以便纳入 API 规范。

然而，现实中，我们常常需要工程师和产品团队自己编写文档，因为他们对 API 最为熟悉，能够提供最准确的信息。

理想的做法是采用一个框架来简化文档编写。例如，FastAPI 可以轻松地将文档嵌入 API 代码中，并生成 OpenAPI 规范。这样，可以通过拉取请求审查或在 CI/CD 管道中进行 linting 检查来确保文档质量。

作为 API 提供商，确保在流程中包含可靠的文档至关重要！

API 文档最佳实践

用清晰的语言书写

确保文档用词清晰明了。避免使用行话，除非它是必要的技术术语，并提供定义或链接到其他文档。设定最低知识要求，定义读者的基础知识，以确保每个文档的内容都能被理解。例如，假设用户知道如何调用 API，但需详细解释如何进行身份验证和 JSON 对象的基本概念。

展示，不要讲述

展示胜于讲述。提供实际的示例能够更好地帮助理解。例如，展示如何从 API 获取数据，包括请求和响应的具体示例。支持多种编程语言的代码示例，以满足不同用户的需求，如 C# 和 Java 代码示例。

添加参考文档、教程和指南

实现不同类型的文档，包括：

教程：学习导向
操作指南：任务导向
解释：理解导向
参考文档：信息导向

参考文档和解释应包含在 API 规范中并托管在公共文档站点上。教程和操作指南则可以放在公共文档站点上，并应包括快速入门指南，以激发用户的兴趣并促进快速上手。

添加代码示例

提供代码示例有助于用户快速了解如何调用 API。示例不仅展示了如何进行 API 调用，还能展示最佳实践，如错误处理和分页处理。

保持最新状态

保持文档与 API 功能同步更新是关键。将文档更新纳入工程和发布流程中，确保新功能和变更都有对应的文档。通过 PR 流程或 CI/CD 管道中的文档检查，确保文档的持续维护。如果有技术作家，可协助更新，否则工程师和产品团队应负责编写和维护文档。

使其可访问

确保文档对所有用户可访问，包括视觉障碍者。使用良好的颜色对比度，提供图像的 alt 文本，并确保文档支持屏幕阅读器。考虑将文档翻译成其他语言，以覆盖不说公司默认语言的用户。

让它成为专人的责任

指定专人负责文档编写和维护。如果文档未准备好，应暂停发布或功能标志。没有专人负责，文档容易被遗忘，导致过时。因此，确保有明确的责任人，以保证文档的质量和时效性。

通过良好的 API 文档让您的 SDK 变得更好

好的 API 文档的另一个显著好处是它可以自动成为 SDK 的文档。使用工具如 liblab，您可以从 API 规范中提取文档和示例，自动包含在生成的 SDK 中。例如，API 规范中的以下组件可以用于生成 SDK 文档：

APITokenRequest:

  properties:

    email:

      type: string

      title: Email

      description: The email address of the user. This must be unique across all users.

    password:

      type: string

      title: Password

      description: The password of the user. This must be at least 8 characters long, and contain at least one letter, one number, and one special character.

通过这种方式，SDK 文档将直接反映 API 规范的内容，确保一致性，并减少维护工作。