诸如 OpenAPI (Swagger) 之类的描述格式以及诸如 Swagger UI 之类的开源实现，改变了 API 团队对 API 文档的看法。通过提供一种以人类和机器都可读的方式定义 API 操作的格式，然后可视化这些操作以让最终用户与 API 的不同端点进行交互——这些工具消除了手动维护 API 文档的需求。
这对 API 团队来说带来了显而易见的好处。
为您的 API 维护准确和最新的文档一直是一个痛苦的过程。即使是有幸聘请技术作家来编写 API“使用手册”的组织和团队，在用新的 API 版本更新文档时仍然面临问题。另一个主要好处是，描述格式及其支持工具帮助生成 API 文档的速度。Swagger UI 是这方面的最佳示例，它允许用户从基本的 API 设计自动生成 API 文档，从而节省了大量的时间和开发人员资源。
在过去的几个月中，SwaggerHub 团队参加了 IBM Interconnect、Microsoft Build 和 DockerCon 2017 等活动，并一次又一次地从开发人员、技术作家、API 设计人员、DevOps 和其他软件专业人员那里了解到 Swagger UI 在生成有用的 API 文档方面的效率。但是，我们从这些对话中学到的另一个教训是，API 用户对 API 文档的期望越来越高，尤其是在 API 经济的竞争生态系统中。
毕竟，虽然为您的 RESTful API 生成一个界面是向最终用户提供文档的良好第一步，但这只是您让人们了解如何有效地使用您的 API 的开始。
您的 API 文档可能缺少的内容
为最终用户生成一个与您的 API 交互的 UI 是提供出色的 API 开发者体验的关键第一步。但在当今的现代 API 经济中，API 在业务和战略增长中发挥着核心作用，文档需要超越基本 UI。
生成此 UI 的目标是提供一个可视资源，最终用户可以使用该资源轻松了解如何使用您的 API。这是使用您的 API 的使用手册，如果此使用手册不完整且对用户没有帮助，则可能会直接损害您的用户的开发者体验并破坏您的 API 计划的成功。因此，重要的是开始考虑如何改进基本的 Swagger UI 和 API 文档，这最终将在使用 API 时带来出色的开发者体验。
以下是您的 API 文档可能缺少的一些关键部分
1. 概述部分
如果您只是为您的 API 生成一个基本的 UI，那么您的文档很可能缺少有用的描述，让人们轻松了解您的 API 的作用以及他们为什么首先要使用它。提供必要的背景信息，以便了解您的 API 的价值，并提供入门介绍。这是您的 API 潜在用户的第一个入口点，因此请确保您专注于您的 API 提供的价值——它做什么，它解决什么问题，以及最终用户应该从使用您的 API 中获得什么结果。在详细说明此部分时，请考虑您的用户试图解决的挑战。这样，概述部分的消息才能真正引起您的目标受众的共鸣。
这是我们最近关于 API 开发者体验的 SwaggerHub 网络研讨会的示例描述：
入门指南
入门指南可以提供有关访问 API 密钥或客户端令牌的信息，以及使用 API 的条款。除了您的 API 的 UI 之外，您还可以包含指向其他参考资料的链接以及有关如何联系您的团队以获得支持或分享反馈的详细信息。该指南应指导您的用户走向成功。我们建议起草指南，帮助用户在 5 分钟内了解您的 API 的价值。请考虑 SwaggerHub 客户 Bandsintown 的这个示例，该公司在其网站上发布了来自 SwaggerHub 的公共 API 文档。
入门指南为启动和运行 Bandsintown API 提供了必要的指导。还有来自 Braintree 和 YouTube 等公司的有用示例，这些公司为开发人员构建了完整的帮助部分，以了解如何使用他们的 API。
请求-响应周期说明
许多 API 团队在描述 API 端点时会做到最少，生成可视化 API 所需的基本框架，而没有添加任何真正的细节来帮助用户了解如何使用它们。这以前可能有效，但在当今竞争激烈的环境中，每天都有新的 API 和解决方案出现，用户有多种选择，他们应该得到完整性。
以每种受支持的格式描述完整的示例响应正文。这不仅包括 XML 或 JSON 数据格式，还包括 HTTP 标头、错误代码和消息。有太多信息可以帮助潜在客户或最终用户学习使用您的 API 绝不是一个坏主意。请记住，良好 API 文档的目标是为您的目标受众提供必要的信息，以了解如何使用您的 API。您应该包括详细的描述，并在必要时提供使用示例。
如果您有技术或领域特定的术语，请将该特定项链接到进一步解释这些术语的文档。这些策略将确保您的 API 的清晰度和良好结构，以及为什么存在某些调用，而不会迷失在参数、标头和响应的细节中。
指向 SDK 和代码库的链接
SDK 库可以帮助用户更快地集成您的 API。它们非常适合让您的用户能够轻松使用您的 API 操作，并基于它们构建丰富的功能和应用程序。如果您已经使用 OpenAPI 规范定义了 API，则可以使用 SwaggerHub 等平台来生成服务器端代码和客户端 SDK，以帮助提高 API 的采用率。
只需单击一下，SwaggerHub 即可生成 HTML 模板，其中包含您的 API 文档和 6 个客户端 SDK 用法示例，以便您的开发人员门户使用，从而使您的开发团队可以非常轻松地进行自定义、交互和工作。您始终可以使用 SwaggerHub 的内置代码生成器进一步将 SDK 添加到 30 多种语言中。
使用 SwaggerHub 完成更多 API 文档工作
如果您已经使用 Swagger 为您的 API 生成交互式 UI，那么您就可以通过像 SwaggerHub 这样的 API 文档工具将您的 API 文档提升到一个新的水平。SwaggerHub 消除了所有基础设施方面的考虑和安全实施问题，使组织能够无缝协作，创建用户和开发团队都会喜欢的优秀 API 文档。了解有关使用 SwaggerHub 记录 API 的更多信息。或者立即免费试用 SwaggerHub。