API 的好坏取决于其文档。如果人们不知道如何使用一个出色的 API，它可能会变得毫无用处，这就是为什么文档对于 API 经济中的成功至关重要。但是，创建和维护易于阅读、互动性强且让用户获得成功的良好文档可能极具挑战性。创建出色的文档需要努力和耐心，但它对 API 的采用和可维护性有直接影响。通过选择正确的API 文档工具，可以使 API 文档的管理更加轻松。在之前的文章中，我详细介绍了良好 API 文档的好处。但是，我们所说的良好文档到底是什么意思呢？ 我们详细介绍了一些好的做法，以帮助您的团队创建受最终用户喜爱的出色 API 文档。 但在我们这样做之前，重要的是要了解一个重要的问题...
您的 API 文档是为谁准备的？
您的 API 旨在解决特定行业中公司面临的实际问题，并将直接由软件工程师集成到应用程序中。因此，您的 API 有两种潜在的受众，他们将影响您 API 的消费和采用曲线。
决策者
这些人评估您 API 的服务，并决定开发团队是否应该花时间探索该服务。他们希望使用您的 API 来解决其产品或服务战略中的潜在挑战。在许多情况下，他们不直接使用您的 API，而是影响组织采用 API 的主要联系人。决策者的示例包括 CTO 或产品经理。
用户
这些人将直接使用您的 API。他们需要了解您 API 的来龙去脉，以及它如何应用于他们的用例。这可能意味着学习如何调用并与您公开的许多或所有资源集成。他们对您 API 的可持续性至关重要。他们具有分析能力，致力于重要且困难的工程问题，并且时间紧迫。因此，您的 API 必须易于使用，并具有出色的文档，以便这些用户可以尽快成功地与您的 API 集成。API 用户的示例包括前端和后端开发人员。 
您的 API 文档需要满足这两种角色。这是一个很难遵循的练习，但它可以确保您的 API 文档是可持续且完整的，从而确保 长期成功和 ROI。
API 文档最佳实践
现在我们已经了解了为谁编写 API 文档，是时候了解一下好的 API 文档实际上包含哪些内容了。
基本 API 文档部分
有一些部分已成为 良好 API 文档的基础。这些部分构成了良好文档的基线，应根据您的 API 预期拥有的行业和消费者类型进行详细说明。这些部分包括：
身份验证
这是有关使用身份验证方案开始使用您的 API 的信息。大多数 API 都有身份验证方案，并且消费者必须先进行身份验证才能获得对 API 的访问权限。请确保正确记录此部分，并引导用户成功地对 API 进行身份验证。Bitly 是一个很好的例子，展示了简洁的身份验证文档。
错误消息
错误消息非常重要，因为它们会告知最终用户何时以不正确的方式与您的 API 服务集成。解释您的错误标准，并提供有关最终用户遇到错误时如何克服错误的解决方案。Mailchimp 在详细说明消费者可能收到的所有可能的错误代码方面做得很好。
资源
请注意您的 API 的资源及其相关的请求和响应周期。资源是 API 的核心组件，用户将不断与之交互。列出您的 API 公开的所有资源，并了解消费者如何与它们集成。这将使您更好地了解如何更好地记录这些资源下的请求和响应。
使用条款
这是消费者与您的组织之间的法律协议，定义了消费者理想情况下应如何使用您的服务。在最佳实践中包括 API 限制以及条款和条件。还需要明确说明约束条件，以便消费者了解允许的 API 用法和实践。这是 Spotify 的 API 使用条款的示例。
变更日志
详细说明您的 API 的更新和版本，以及这可能会如何影响 API 消费者。这将帮助消费者了解您的 API 的稳定性，并查看是否需要对有效的 API 调用进行任何更改。这是 GitHub 的 API 变更日志的示例。在开始 API 文档之前映射上述部分，是技术作家确定重要优先事项的好方法。
避免使用术语
请记住，许多使用 API 的人员可能不熟悉您使用的领域知识或术语。文档应面向“技术型”开发人员受众，以及技术水平较低的决策者（如产品经理）。技术写作团队常犯的一个错误是假设他们的受众完全是技术人员，并且完全了解如何使用 API。 首先，您的文档应使用通俗易懂的语言编写，并为每个资源提供易于理解的领域解释。避免使用过多的技术术语，并以对 API 或行业新手易于理解的方式进行编写。 如果您确实有技术或特定领域的术语，请将该特定项链接到进一步解释这些术语的文档。这将确保您的 API 的清晰度和完整性，帮助用户了解某些调用的存在原因，并避免在参数、标头和响应的细节中迷失。 一个很好的例子是Stripe 的 API 文档，他们有意识地避免使用技术性词语。即使存在基于领域的术语，他们也会通过额外的内容来解释其含义。 YouTube 的 API 以其完整性和清晰度而闻名，使开发人员可以轻松理解 API 的工作原理。他们还有一个很好的左侧导航面板，可以轻松访问各种资源实现的文档，我个人觉得这非常有益。
认真对待您的请求和响应
认真对待您的请求-响应周期的文档。为最终用户提供过多的信息永远不是问题，尤其是当他们试图将您的服务集成到他们的应用程序中时，因此请详细描述您的请求-响应周期。 记录您的 API 可以提供的每个调用，并提供有关参数和响应的上下文。 响应是您用户的指南，指示他们是否走对了方向，或通过错误消息提供指导以帮助他们成功。您的 API 用户应该确切地知道从成功的 API 调用中会得到什么。 以每种支持的格式描述完整的示例响应主体。不仅要考虑 XML 或 JSON 等格式，还要考虑 HTTP 标头、错误代码和消息。 参数和响应中的示例也很重要。在您的 API 应返回的每个对象中提供示例，以及用户可以添加以成功进行 API 调用的参数示例。 这是另一个Stripe 的出色文档示例，以及他们如何详细描述错误响应。 另一个请求和响应文档的优秀示例是Instagram。
为您的文档提供资源
您可以向您的用户提供其他信息和资源，以便他们成功使用您的 API。优秀的 API 文档不仅仅是基本内容和生成的 Swagger UI，更重要的是确保您的用户和潜在客户尽快成功使用您的 API。您可以使用其他资源来补充您的文档，例如：
入门指南
入门指南详细介绍了如何快速开始使用您的 API。该指南的重点应放在确保用户尽快成功使用您的 API 上，并在此过程中为他们提供指导。一个好的入门指南的例子是 Braintree，它很好地概述了如何集成和使用他们的 API。
SDK 和库
代码库可以帮助开发人员快速调用不同的资源。使用各种语言的快速简便的方法来使用您的 API 可以使开发人员在使用 API 时感到更舒适。SDK 很难构建，而且对于发布来说不是至关重要的，但可以为提高 API 的采用率做出巨大贡献。如果您的商业模式是公共的开放 API 模型，那么拥有 SDK 是与开发人员社区互动的绝佳方式。在这种情况下，如果开发人员发现您的 SDK 和 API 的价值，他们很有可能会在其基础上构建，或添加更多的库。Swagger Codegen 项目可以帮助团队直接从他们的 API 文档中快速生成 SDK。
交互式控制台
鼓励潜在客户立即使用 API 控制台测试他们在 API 文档中读取的内容。实验非常强大，控制台可以使入门变得容易，并且从用户的角度来看责任有限。为人们创建控制台或沙箱环境以与您的 API 交互相对来说很简单，但可以在帮助开发人员直观地了解您的 API 的价值方面发挥重要作用。许多公司，如GitHub 和Microsoft，都提供交互式控制台来使用他们的 API 产品。
优秀的 API 文档需要努力，但这是值得的
我们一直认为 API 文档是推动 API 增长和成熟的强大工具。它是使用 API 时良好开发人员体验的基础。 希望通过上述提示，您通往优秀文档的旅程会更加轻松。流行的开源描述格式，如OpenAPI 规范和商业平台，如SwaggerHub，使团队可以自动化文档流程，并致力于提供出色的 API 使用整体体验。 您可以在此处探索 SwaggerHub 的 API 文档功能，或免费亲自试用。
网络研讨会：将企业转变为 API 平台的经验教训
您的数字化转型工作是否将您的业务引向正确的方向？在 4 月 10 日，我们将举办一次免费的网络研讨会：将企业转变为 API 平台的经验教训。本次会议重点介绍在与酒店、贷款发起和金融科技等各组织合作开发和部署其 API 平台过程中汲取的经验教训。这些企业实施了 API 优先设计、联合治理和 API 管理层，作为其整体平台战略的一部分。我们将探讨哪些方法有效，哪些方法无效，以及简化您的转型计划的技巧。将讨论的主题：
- 开发有效的 API 项目，以促进内部重用和蓬勃发展的合作伙伴项目
- 实施 API 治理的技术，包括探索集中式与联合式治理
- 微服务和模块化软件设计如何改变当今企业的文化
- 通过开发出色的门户和开发人员支持流程来提高 API 的入职和采用率
- 通过以 API 为中心的企业方法加速转型计划的技巧
立即注册 