API 格局正在快速增长。 组织比以往任何时候都更依赖于连接的网络服务和集成，提供商有机会大幅增加其 API 的采用率。
开发人员希望使用易于学习并按预期执行的 API。 高质量的文档可以设定期望、教育用户，并吸引开发人员开始使用您的服务进行新项目。
以下是您的团队设计一流文档的一些方法
1. 讲述一个宏大的故事
当有人第一次查看您的 API 文档时，他们会看到什么？
如果您试图推动采用并建立 регулярных пользователей 群体，您应该讲述一个故事。 文档可能名声不好，因为它通常是技术性和详尽的，但对于许多公司来说，文档现在既是其产品的包装又是使用说明。
您的故事是什么？ 您的 API 的使用者在这个故事中扮演什么角色？ 例如，漫威有一个公共 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 文档中寻找的 5 个最重要的事项”。 这是来自 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 文档的信息
想阅读更多关于文档最佳实践的信息吗？这些是我们最喜欢的关于该主题的一些文章，其中许多文章都帮助我们撰写了这篇文章。去看看吧！
阅读更多