良好的用户体验是使用任何产品的关键，对于 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 规范在 Swagger 团队加入 SmartBear 且该规范于 2015 年捐赠给 OpenAPI Initiative 后，更名为 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 是一种广泛使用的文档可视化工具。它不仅用于内部消费，也用于外部采用。Swagger UI 内置交互性，因此外部消费者可以在将其用于代码库之前尝试 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 定义。使用 Swagger Inspector，通过调用每个端点并使用相关响应生成符合 OAS 的文档，或将一系列调用串联起来为多个 API 端点生成完整的 OAS 文档，从而快速为现有 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 规范。
生成的定义将为您的团队构建 API 文档提供符合 OAS 的结构。有了定义，您可以添加重要细节，例如：支持的内容类型、描述、示例、认证类型等等。
我们将在本资源的后续部分详细介绍如何继续构建您的 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 上获取。为了运行 Swagger Core，需要将这些 Maven 依赖项添加到您的 JAX-RS 编码 API 中。
一个典型的 Maven 依赖项如下所示：
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-jersey-jaxrs</artifactId>
<version>1.5.12</version>
</dependency>
由于 Jersey REST 框架主要版本的差异，用户应为 Jersey 2.x 使用 swagger-jersey2-jaxrs 依赖项。下一步是将 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 符合您的组织设计标准，以改善消费者的体验。不再需要您的开发人员参考维基页面、GitHub 文档或 PDF 来保持 API 之间的样式一致性，SwaggerHub 会为您进行标准化。
- 协作与问题跟踪：在集中式平台上与多个利益相关者协作。SwaggerHub 为团队提供了一个平台，用于在整个设计和文档化过程中进行协作，通过 SwaggerHub 编辑器中的评论实时收集反馈和跟踪问题。
- 部署到 API 网关：SwaggerHub 充当您的 API 定义的真相来源，让您可以在云端处理您的设计和文档工作，并将您的 OAS 定义无缝推送到 AWS、Microsoft Azure、Apigee 等 API 网关。
免费开始！
将 OAS 与 Swagger 工具结合使用可缓解文档化方面的担忧，创建交互式文档，这些文档是自动生成的，并且只需要最少的维护。需要为现有 API 集生成 OpenAPI 定义吗？试试 Swagger Inspector。
希望标准化您的设计和文档化流程？立即开始使用 SwaggerHub。