API 格局正在迅速发展。组织对互联网络服务和集成的依赖比以往任何时候都高，而提供商则有机会大幅提高其 API 的采用率。
开发者希望使用易于学习且性能符合预期的 API。高质量的文档可以设定预期、教育用户，并吸引开发者使用您的服务启动新项目。
以下是您的团队设计一流文档的一些方法
1. 讲述一个宏大的故事
当有人首次查看您的 API 文档时，他们会看到什么？
如果您正在努力提高采用率并建立稳定的用户群，您应该讲述一个故事。文档通常因技术性和详尽性而名声不佳，但对于许多公司而言，文档现在既是其产品的包装，又是使用说明书。
您的故事是什么？API 用户在故事中扮演什么角色？例如，漫威（Marvel）有一个公共 API，允许开发者查询漫画书正典。
漫威 API 文档： https://developer.marvel.com/docs
当有人访问门户时，故事一目了然：“用世界上最伟大的漫画 API 创造非凡内容”。
您的组织的 API 可能不依赖超能力，但很可能有一个故事能体现您的优势，并让开发者兴奋地使用您的 API。
2. 提供一个清晰的起点
好了，您已经用一个引人入胜的故事聚集了新用户。接下来呢？
提供一个清晰的起点，让开发者知道从何处开始熟悉您的 API。流行的消息工具 Slack 的 API 文档在这方面做得很好。他们用一个动态标题“构建：出色的机器人”讲述了一个故事，并用一个“从这里开始”部分介绍了他们的侧边栏导航。
Slack API 文档： https://api.slack.com/
在用户甚至滚动页面之前，他们就有一个清晰的起点来学习 API，这同时也为 Slack 提供了一个专门的地方来设定新用户的预期。“从这里开始”部分与标准的软件开发生命周期相符，从规划、设计到构建。考虑哪种结构对您的 API 最有意义，但请确保在用户首次访问您的文档时为他们提供方向。
3. 创建一个便于常见用例的结构
除非开发者只是纯粹浏览，否则当他们到达您的文档时，很可能已经有了一个项目构想。通过突出显示您的 API 可以支持的最常见用例或操作，您可以减少开发者查找所需信息的时间。Slack 在这方面也做得很好，在其主页上指出了“发送消息”、“创建简单工作流”和“构建机器人”等操作。
花时间考虑您的最终用户正在尝试构建什么类型的东西，以及如何提前向他们提供所有最有用的信息。如果您能让他们第一次使用您的 API 的项目变得轻松，您就会增加他们定期回访的可能性。
4. 首先为人类编写
某些开发者可能除了您的文档之外，永远不会与您的组织进行互动。如果您的文档全是专业且枯燥的，开发者可能会找到他们所需的信息，但体验不会令人印象深刻。思考一下您文档的语气。它是对话式的吗？
如果开发者坐在您旁边，您会如何解释身份验证选项？
您需要值得信赖，因此不要过多地使用俚语或过度夸张，但也不要枯燥和神秘。要开始，您可能想将现有文档通过一个可读性计算器进行检查。
这些计算器将帮助您保持诚实，并突出显示您可能存在长句或过多长单词的部分。编码已经够难了；阅读应该轻松。
5. 使其全面
开发者对提供商的 API 文档期望很高。在我们的2019 年 API 现状报告中，我们要求受访者选择“在 API 文档中您最看重的五件事”。以下是来自 3,000 多名软件专业人士的结果：
确保您向用户提供的资源是详尽的。想象一下最积极的用户可能会访问您的文档，不要让文档的缺乏阻碍他们。
这并不意味着向用户提供所有可能的信息。在您的文档中采用层级结构，以便轻度用户可以快速了解常见用例，而高级用户则可以随意点击查看详细信息。
6. 使其互动化
在上图中，受访者选择“示例”作为 API 文档最重要的组成部分。开发者希望尽快亲身体验，了解您的 API 可能实现的功能。
借助交互式文档，开发者可以快速测试不同的 API 调用。我们之前提到的漫威门户就提供了此选项。当您创建帐户时，会自动获得一个 API 密钥。您可以使用该密钥对所有不同的端点进行调用并测试不同的操作。此交互页面还有助于开发者熟悉他们应该预期的参数和错误消息。
漫威的交互式文档： https://developer.marvel.com/docs
7. 使用 OpenAPI 规范标准化您的 API 设计
OpenAPI 规范（以前称为 Swagger 规范）是一种用于 REST API 的 API 描述格式，已迅速成为行业标准。在我们的2019 年 API 现状调查中，我们发现近 70% 的受访者目前正在使用 Swagger/OpenAPI 标准来定义他们的 API。
这种格式旨在易于学习，并且对人类和机器都可读。
通过以一致的方式构建您的 API，您的组织能够为开发者提供一致的体验。他们将知道会发生什么以及在哪里找到它。
采用 OpenAPI 规范的组织可以利用 SwaggerUI 等开源工具，自动将其 API 定义转换为交互式文档。
您可以通过访问 Swagger Petstore 查看 SwaggerUI 的文档工作方式：https://petstore.swagger.io/
SwaggerUI 以及所有其他 Swagger 开源工具都可在名为 SwaggerHub 的一个集中平台上使用。如果您的团队希望围绕 OpenAPI 规范进行标准化，您可以创建一个免费帐户并立即开始导入您的 API。
8. 突出显示教程、常见问题和案例研究
您的文档是您 API 的学习平台。
您可以解释如何使用您的 API，但展示如何使用您的 API 才能真正使其生动起来。为简单的项目类型创建教程，然后将其链接到您的文档中。下面来自 Slack 的示例展示了他们正在构建和推广的文章和教程类型，以帮助用户了解他们的 API。
Slack API 教程： https://api.slack.com/tutorials
他们还列出了一些案例研究。为了真正推动您的 API 的采用，您不仅应该教育访问者，还应该为他们提供新项目的灵感。
Slack 引用的一个创意示例是 Kip，一个企鹅主题机器人，帮助办公室协调食物订单。通过突出显示一些最具创意的用户，让开发者轻松了解您的 API 可以实现什么。
9. 鼓励用户反馈
您的文档效果如何？
您可以查看不同的指标作为代理，例如页面浏览量、消费者数量或调用次数，但仅凭这些指标，您的团队将不得不做出许多假设。
您可以调查用户并了解他们的想法，但如果用户反馈没有内置到您的流程或基础设施中，那么在请求用户反馈方面保持纪律性可能会很困难。最好的文档会鼓励用户在文档内部提供反馈。
流行的支付供应商 Stripe 在这方面做得很好，他们在文档的每个部分末尾都会询问“本节是否有帮助？”。用户在浏览时只需很少的时间就可以点击“是”或“否”。
通过提出这个问题，他们可以清楚地看到哪些部分被标记为最无用，哪些部分拥有最活跃的访问者，然后相应地优先进行改进。
Stripe API 文档： https://stripe.com/docs/api
这个元素为您现有的文档提供了一个量化衡量标准，但您仍然不知道可能缺少什么。通过将嵌入式量化衡量与定性调查相结合，您可以很好地了解文档的现状。
10. 保持更新
阅读只会让事情变得更混乱的文档确实令人沮丧。
如果您的文档没有及时更新，它可能会对您的组织产生负面影响，并阻碍开发者使用您的 API。
在我们的2019 年 API 现状报告中，我们询问受访者：“提供最新 API 文档的最大障碍是什么？”前 3 个回答是：
- 因工作量缺乏时间或资源
- 对交付速度的需求不断增加
- 缺乏工具或技术
为了应对这些挑战，您的团队必须依赖能够加快流程并为您节省时间的工具。我们已经提到过像 SwaggerUI 和 SwaggerHub 平台这样的工具如何自动为您的 API 定义生成文档。
除此之外，还要寻找那些会拖慢您团队的依赖项。您的文档团队是否必须等待开发工作完成才能开始？
等待其他团队的工作会造成可避免的时间紧缩，并随后损害您的文档质量。
如果您的团队正在使用 OpenAPI 规范，像 ServiceV Pro 和 VirtServer 这样的工具可以轻松地将您的 API 设计转换为可在团队之间共享的虚拟服务。
您的文档、开发和测试团队都可以使用虚拟服务并行工作。通过为项目设置一个共享的“单一真相源”，您可以开始准确地记录预期响应，而无需等待其他团队。
如果您的团队正在使用 SwaggerHub，它与 ServiceV 有一个简单的集成，使虚拟化成为您工作流程的自然组成部分。
了解更多关于 API 文档的信息
想了解更多关于文档最佳实践的信息吗？这些是我们最喜欢的一些相关文章，其中许多都为本文提供了参考。去看看吧！
阅读更多