像 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。