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 文档具有可持续性和完整性，从而确保长期成功和投资回报。
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 为中心的企业方法，加速您的转型举措的技巧
立即注册 