良好的用户体验是使用任何产品的关键，API 也是如此。用于消费 API 的接口越好，实现业务和技术目标的机会就越高。
自从移动和云计算出现以来，API 已经成为主流，越来越多的公司和组织理解了创建 API 的商业价值。随着大量 Web 服务的出现，明确 API 文档以采用这些服务的需求变得清晰。
API 文档是成功使用和集成 API 所需的信息。这可以是技术写作、代码示例和示例的形式，以便更好地理解如何使用 API。简洁明了的文档——让您的 API 用户能够快速将其应用到他们的应用程序中——对于希望推动其 API 采用的组织来说不再是可选的。
为什么文档很重要
ProgrammableWeb 的一项调查发现，API 用户认为完整准确的文档是他们 API 决策中最大的因素，甚至超过了价格和 API 性能。
良好的文档可以加速开发和使用，并减少回答支持电话所花费的金钱和时间。文档是整体用户体验的一部分，也是增加 API 增长和使用的最大因素之一。
API 文档的挑战
API 像许多其他产品一样，在开发和发布周期中往往会快速发展。为您的开发团队和最终用户维护和更新此文档，以便他们高效地使用 API，变得非常困难。如果您使用静态文档（如 .pdf）向最终用户提供文档，则尤其如此。第二个问题是促进多个 Web 服务之间的交互。应用程序由多个不断相互通信和交互的服务组成。
随着 RESTful 服务的数量增加，用于实现它们的编程语言也在增加，这使得它们更难进行通信。API 文档可以被认为是使用 API 的接口，因此需要促进这些不同 Web 服务之间的交互。常规的 API 接口（无论是文本文档还是其他如 Javadocs）不允许它们相互通信。这些挑战以及其他 API 痛点导致了 Swagger 规范的创建。
在下一节中，我们将更仔细地研究 OpenAPI 规范（以前称为 Swagger 规范）如何帮助解决您的文档挑战。
为什么将 OpenAPI 用于 API 文档
在 Swagger 团队加入 SmartBear 并将规范捐赠给 2015 年的 OpenAPI Initiative 后，Swagger 规范被重命名为 OpenAPI 规范 (OAS)，现已成为定义 RESTful API 的事实标准。
（注意：我们将在本资源中使用术语 OpenAPI 和 OAS。这指的是规范。）
OAS 定义了 API 的合同，允许所有 API 的利益相关者（无论是您的开发团队还是您的最终用户）了解 API 的功能，并与它的各种资源进行交互，而无需将其集成到他们自己的应用程序中。此合同与语言无关且人类可读，允许机器和人类解析并理解 API 的预期功能。
OAS 合同描述了 API 的功能，它的请求参数和响应对象，所有这些都没有任何代码实现的指示。使用 OAS 定义的 Web 服务可以相互通信，而无需考虑它们构建所用的语言，因为 OAS 与语言无关且机器可读。
OAS 如何帮助文档？
Swagger 最初获得采用的最大原因之一是它能够帮助简化 RESTful API 的文档。使用 Swagger UI 等工具（无论是开源还是在 SwaggerHub 平台中）可以将您的 OAS 合同转换为交互式 API 控制台，用户可以使用该控制台与 API 进行交互并快速了解 API 的预期行为。
为您的 API 生成文档只是使用 OpenAPI 定义 API 的优势之一。其他好处包括
- 帮助内部团队成员了解 API 并就其属性达成一致：API 定义允许 Swagger UI 等文档工具可视化 API。您可以可视化我们所有的内部 API，以便开发人员可以快速轻松地使用上游和下游服务。像 SwaggerHub 这样的基于团队的工具允许在 API 文档上进行协作，并将其托管供内部使用。
- 帮助外部人员了解 API 及其功能：同样，Swagger UI 是一种常用的可视化文档工具。不仅适用于内部使用，也适用于外部采用。SwaggerUI 内置了交互性，因此外部用户可以在代码库中使用之前尝试 API 的每个资源并熟悉它。使用 SwaggerHub 平台，组织还可以为其外部用户提供受控访问。
- 为您的 API 创建测试：您的 OAS 定义提供了一个合同，该合同描述了当有人调用您的 API 时成功的响应会是什么样子。此合同还可以重新用于生成测试用例，这可以大大减少团队测试 API 所需的设置量。
- 生成实现代码和 SDK：除了生成文档外，OpenAPI 定义还可以通过为 API 搭建实现代码和 SDK 来加速开发。API 定义文件可以导入到许多不同的工具中，例如 Swagger Codegen 和 SwaggerHub，以使用多种不同的语言（例如 Java、Scala 和 Ruby）创建这些存根代码。
现在我们已经介绍了为什么您的团队应该将 OAS 和 Swagger 工具采用到您的 API 开发工作流程中，下一个问题是如何真正开始？在下一节中，我们将更仔细地研究开始使用 OAS 的不同方法。
OpenAPI 的方法
在创建 OAS 定义时，出现了两个重要的思想流派：API 开发的“设计优先”和“代码优先”方法。
设计优先方法提倡在编写任何代码之前首先设计 API 的合同。这是一种相对较新的方法，但随着 OpenAPI 的使用，它正在迅速流行起来。在设计优先方法中，API 合同充当中心草案，使您的所有团队成员都了解 API 的目标以及如何公开 API 的资源。
在编写任何代码之前发现设计中的问题，比在实现已经到位后这样做要有效得多，也更流畅。
如果您的团队已准备好过渡到设计优先方法，您首先需要熟悉编写 API 定义。以下是一些可以帮助您开始此过程的资源
“代码优先”方法
代码优先方法（也通常称为“自下而上”方法）是一种更传统的构建 API 的方法，在业务需求确定后进行代码开发，然后从代码中完成 API 的文档编制。
对于许多 API 团队来说，开始使用 OpenAPI 意味着从“代码优先”方法开始，并从现有的一组 API 生成定义。让我们探讨一些在您已经拥有现有 API 时生成 OAS 定义的其他常用方法。
使用 Inspector 生成 OAS 定义
Swagger Inspector 是一款易于使用的开发者工具，可以快速执行任何 API 请求、验证其响应并生成相应的 OpenAPI 定义。通过调用每个端点并使用关联的响应来生成符合 OAS 标准的文档，或者将一系列调用串联起来为多个 API 端点生成完整的 OAS 文档，使用 Swagger Inspector 可以为现有的 REST API 快速生成基于 OAS 的文档。
使用 Swagger Inspector，您可以直接从浏览器窗口执行快速 API 调用。在您执行第一次调用后，您可以创建一个免费帐户并将您的调用历史记录保存在 Inspector 中。
使用 Swagger Inspector，您可以为调用的任何端点自动生成 OpenAPI 文件，从而节省宝贵的开发时间，并允许您的技术文档编写人员开始创建出色的文档。
Swagger Inspector 与 SwaggerHub 集成，SwaggerHub 是面向团队的 API 设计和文档平台。 通过集成，开发人员可以自动在 SwaggerHub 上托管和可视化他们的 API 文档，以实现内部和外部利益相关者的 API 发现和使用。
如何从现有 API 生成 OpenAPI
前往Swagger Inspector，插入您想要记录的资源的端点。然后，您可以从 Swagger Inspector 的“历史记录”部分导航到右侧面板，并单击“创建 API 定义”来创建 OAS 定义。
Inspector 的妙处在于，您可以选择多个端点，并通过集合将它们的文档合并到一个 OpenAPI 文件中。
您需要一个 SwaggerHub 帐户才能在 SwaggerHub 上托管生成的 OpenAPI 文件，以及在 Swagger Inspector 中保存您的调用历史记录。
如果您已经拥有 SwaggerHub 帐户，则可以使用您的凭据登录 Swagger Inspector。当您创建 Swagger Inspector 帐户时，您会自动加入 SwaggerHub 系列。创建帐户后，您可以随时随地轻松访问历史记录中的所有测试，也可以在 Inspector 中单击按钮生成相应的 OpenAPI 规范。
生成的定义将为您的团队提供符合 OAS 标准的结构，以构建您的 API 文档。有了定义，您可以添加重要的详细信息，例如：支持的内容类型、描述、示例、身份验证类型等。
在本资源的后面，我们将更详细地介绍如何继续构建您的 API 文档，但首先，让我们探讨一些其他流行的生成 OAS 定义的方法。
运行时 OAS 生成
Swagger-core 是 Swagger 的 Java 实现。当前版本支持 JAX-RS 和普通 servlet。
在这种方法中，Swagger/OAS 契约是从 API 基于针对各种资源、方法和控制器添加的元数据生成的。此元数据将在运行时生成契约、客户端代码和其他工件。通常，此元数据将以代码注释的形式出现。当针对其资源调用各种方法和函数时，工具会触发，并从 API 中定义的元数据生成 OAS 契约。
为了更好地阐述此过程，让我们考虑一个案例，其中我们必须从使用 JAX-RS 和 Jersey 框架编码的 API 生成 OpenAPI 规范。
从现有 API 生成 OAS 文档需要三个步骤
- 将依赖项添加到您的应用程序
- 将 Swagger Core 连接到应用程序
- 初始化 OAS 契约
Swagger 项目使用 maven 来构建和部署工件，这些工件在 Maven Central 上可用。需要将这些 maven 依赖项添加到您的 JAX-RS 编码 API 中，才能运行 Swagger Core。
一个典型的 maven 依赖项如下所示
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-jersey-jaxrs</artifactId>
<version>1.5.12</version>
</dependency>
由于 Jersey REST 框架的主要版本存在差异，用户应使用 swagger-jersey2-jaxrs 依赖项用于 Jersey 2.x。下一步是将 Swagger Core 连接到您的 API 中。根据 Jersey 在您的 Web 服务中的配置方式，您可以使用 Spring、Jersey 的容器 Servlet 或手动方式将 Swagger Core 连接到您的应用程序。
最后，根据在前几个步骤中添加的代码注释，可以在应用程序运行时初始化 OAS 定义。生成的 OAS 定义将位于两个文件中，分别以 JSON 和 YAML 定义。
以下是一些其他资源，可以帮助您更好地理解此过程
- 为 Jersey 项目生成 Swagger
- 为基于 Spring 的 API 生成 Swagger
- 为基于 PHP 的 API 生成 Swagger
构建时 Swagger 生成
在这种方法中，OAS 契约是在预处理 API 时生成的，即在运行时之前。API 中针对各种资源、方法和函数的注释有助于生成 OAS 定义。这些注释通常采用预定义的特殊语法，具体取决于您用于生成契约的工具类型。该工具会扫描您的 API 代码中的这些特殊注释，并生成 OAS 契约作为输出。Cakephp-swagger 和 grape-swagger 是在构建时生成 OAS 契约的工具的突出示例。
任何方法都有其优缺点。就易用性和速度而言，Swagger Inspector 胜过其他方法。只需点击五次，用户就可以从托管在 SwaggerHub 上的现有 API 中获得完全结构的 OAS 定义。
Swagger Inspector 仅生成最终文档的基础，文档编写人员仍然需要花费时间来准确详细地描述资源、方法以及如何向使用者使用它们。在运行时生成 OAS 规范会从代码中生成更准确的 API 契约，但代价是额外的依赖项形式的软件负载、开发时间，并且可能会给系统增加一些开销。
相反，在 API 运行时之前生成 OAS 契约是一个更轻量级的过程，但所产生的 OAS 契约很可能无法准确描述您的 API，因为它必须手动维护。在这两种方法中，可能都需要进行一些额外的工作，以确保生成的 OAS 文件准确表示您的 API 的操作。
从 OAS 定义记录 API
无论您采用哪种方法生成 OAS 定义，仍然需要大量额外的工作来构建您的 API 文档。
借助 Swagger Inspector 或 Swagger Core 等出色工具，您将拥有符合 OAS 标准的结构，这将使您可以轻松地为每个 API 端点填写重要的详细信息。生成的文件是您 API 的技术文档和交互式文档的基础。
从生成的契约进行文档编写意味着添加有意义、易于理解的信息，您的最终用户可以使用这些信息来实现 API 的成功。OAS 允许您描述重要的详细信息，包括
- 媒体类型：媒体类型是请求或响应正文数据的格式。Web 服务操作可以接受和返回不同格式的数据，最常见的是 JSON、XML 和图像。
- 端点/资源：这些可能具有可选的简短摘要和更长的描述，用于文档编写。此信息应该与此端点中的所有操作相关。描述可以是多行的，并支持 Markdown (CommonMark) 以进行富文本表示。
- 请求正文：请求正文通常与“创建”和“更新”操作（POST、PUT、PATCH）一起使用。例如，当使用 POST 或 PUT 创建资源时，请求正文通常包含要创建的资源的表示形式。
- 响应：API 定义需要指定所有 API 操作的响应。每个操作必须至少定义一个响应，通常是成功的响应。响应由其 HTTP 状态代码以及响应正文和/或标头中返回的数据定义。
- 身份验证：身份验证通过使用 securityDefinitions 和 security 关键字进行描述。您可以使用 securityDefinitions 来定义 API 支持的所有身份验证类型，然后使用 security 将特定的身份验证类型应用于整个 API 或单个操作。
- 示例：您可以向参数、属性和对象添加示例，以使您的 Web 服务的 OpenAPI 规范更清晰。示例可以被以某种方式处理 API 的工具和库读取。
这些只是可以在您的 OAS 定义中定义的几种信息类型。您可以在此处了解有关使用 OAS 记录 API 的更多信息。
请记住，文档是您 API 的使用手册，并且是实现 API 业务目标的最大驱动因素之一。创建您的用户会喜欢的 API 文档需要付出努力，但是这种投资将以出色的开发者体验、更简单的实施以及 API 采用率的提高而获得可观的回报。
在最后一部分中，我们将了解 SwaggerHub 如何使用 OAS 进一步帮助您的 API 文档工作流程。
SwaggerHub 中的 API 设计和文档
文档可能是一个棘手的过程。这是一项手动的协作操作，需要文档编写人员投入大量的时间、质量和同理心。在从 API 代码到文档的旅程中，最重要的是拥有一个无缝的工作流程，而不会因额外的设置而让您感到麻烦。通常建议对 API 文档进行独特地关注和处理，因为文档是用户和客户使用您的 API 产品时使用的第一个接口。
SwaggerHub 是一个集成的 API 设计和文档平台，专为团队构建，可在整个 API 开发工作流程中推动一致性和规范性。它是一个专用的工作平台，可以处理所有配置和托管，从而使您可以将文档无缝集成到您的 API 工作流程中。
一旦您的 API 合约从现有 API 代码生成，您就可以将其导入 SwaggerHub，并继续您的 API 之旅。交互式文档会自动生成并托管在 SwaggerHub 上。您可以编辑定义，您的技术文档编写人员可以在 API 中添加正确的信息，从而为消费者提供集成所需的必要信息。SwaggerHub 的内置工具进一步辅助文档编写过程。
其中一些工具包括：
- 安全的云托管：将您的 API 定义存储在专为 API 构建的平台上。SwaggerHub 在整个文档编写过程中自动保存您的工作，并提供一个集中托管文档的地方，无需设置服务器。
- 标准化和治理：使您的所有 API 都符合您的组织设计标准，以改善消费者的体验。不再需要 Wiki 页面、GitHub 文档或 PDF，您的开发人员必须参考这些文档来维护 API 的样式一致性，SwaggerHub 将为您标准化这些内容。
- 协作与问题跟踪：在集中式平台上与多个利益相关者合作。SwaggerHub 为团队提供了一个在整个设计和文档编写过程中协作的平台，通过 SwaggerHub 编辑器中的注释实时收集反馈和跟踪问题。
- 部署到 API 网关：SwaggerHub 作为您 API 定义的真理来源，让您可以在云端处理设计和文档编写工作，并将您的 OAS 定义无缝推送到 AWS、Microsoft Azure、Apigee 等 API 网关。
免费开始使用！
将 OAS 与 Swagger 工具结合使用可以减轻文档方面的担忧，创建自动生成且只需最少维护的交互式文档。需要为现有 API 集生成 OpenAPI 定义吗？尝试使用 Swagger Inspector。
希望标准化您的设计和文档流程吗？立即开始使用 SwaggerHub。