Swagger 教程

Swagger 是记录标准 API 的标准方式。Swagger 在 Azure 中部署 API 时很有帮助。Swagger 主要用于记录 API；现在的问题是，为什么要记录 API？无论是构建企业内部 API 还是面向公众的 API，主题都是相同的，即开发人员通常会在他们构建的应用程序中使用。为了让其他开发人员能够使用我们的 API，API 必须得到妥善记录；否则，他们怎么会知道 API 暴露了哪些端点以及在这些端点上支持哪些操作？他们应该传递什么参数，他们会得到什么返回？使用什么身份验证方法？为了回答这些问题，记录 API 非常重要；如果您希望 API 被消耗和正确使用。

Swagger 和 Open API 规范是记录 API 的方法，它指定了 API 究竟能做什么。

什么是 API？

API 代表 应用程序编程接口。 它定义了两个软件如何相互通信。API 有多种类型，但 Swagger 特别处理 Web API。

Web API 如何工作？

让我们通过一个例子来理解 Web API 的工作原理。假设我们在手机上打开了 Facebook 并向 Facebook 服务器发送了一个请求。发送到 Facebook 服务器的请求称为 API 请求，Facebook 服务器将发送一个称为 API 响应的响应。服务器只发送数据，而不发送整个网页。由应用程序负责显示网页。

此处，API 定义工作原理

• 有哪些可用请求
• 每个请求的响应是什么样的。

Swagger 和 Open API 规范主要针对 REST API 设计，其中 REST 是一种 Web API。在 REST 中，R 代表 Representational（表示），S 代表 State（状态），T 代表 Transfer（传输）。

什么是 API 定义？

API 定义是一个文件，描述了我们可以使用 API 完成的所有事情。它包含我们可以向 API 发出的所有请求。它还描述了应该发出什么请求，以及每个请求的响应将是什么样子。

为什么要创建 API 定义？

编写 API 定义有几个优点

• 它允许您在实现 API 之前设计 API。开发人员可以在编写 API 代码之前审查 API。
• 它还有助于自动化测试。
• 它可以自动用多种语言创建代码。
• 它还可以用于自动生成文档。

API 定义文件

API 定义文件是包含您可以对文件执行的所有操作的文件。此文件包含以下内容：

• 服务器位置
• 如何处理安全，即授权。
• 该 API 中所有可用的资源。
• 您可以在请求中发送的所有不同数据。
• 返回什么数据
• 可以返回的 HTTP 状态码

请求的结构

HTTP 请求中可以找到五个不同的部分

1. 方法：方法描述要执行的操作。方法可以是 POST、PUT、DELETE、GET。
2. URL：它指定要执行操作的名称。
3. 查询参数
4. 标头：标头用于存储有关请求的信息。
5. 正文：正文包含额外数据。

URL 被分解成几个部分

例如：请求 URL 是：https://api.example.com/v2/user

• 方案：https
• 主机：api.example.com
• 基本路径：/v2
• 路径：user

注意：对于一个 API，主机和基本路径保持不变，但路径会根据请求而有所不同。

请求正文

我们主要以 JSON 格式指定请求正文，用于某些方法，如 PUT、POST 等。正文被视为 URL 中的路径参数。与这些参数不同，我们为请求正文创建模式，该模式指定 JSON 正文的外观。

在 REST 中，响应正文可以是任何内容，但主要响应正文以 JSON 格式书写。响应正文包含在响应对象中。响应正文有一个模式来表示结构化数据。我们也可以为每个返回的 HTTP 状态码有一个单独的响应对象。

安全性

此处，安全性是指身份验证和授权。身份验证是指通过用户的用户名和密码验证用户。授权是指允许用户访问数据。

可以通过以下方式设置安全性

• 无：在此，无意味着没有设置安全性来访问 API。
• 基本身份验证：这意味着每次请求都设置了用户名和密码。
• API 密钥：设置密钥以访问 API。
• OAUTH：这是一个授权方案。

文档

OAS 文件或 API 文件包含元素的易于阅读的描述，这些元素会自动生成文档。换句话说，我们可以说，为 API、为每个操作（路径和方法的组合）、为每个参数和为每个响应元素添加了描述部分。

结构化数据格式

Open API 规范在其 API 定义文件中使用结构化数据格式。我们可以使用两种结构化格式之一，YAML 或 JSON。

YAML

YAML 代表 Ain't Markup Language (不是标记语言)。 它不像 HTML 那样是标记语言。它用于数据，而不是内容。YAML 与 JSON 和 XML 相比使用的字符最少。它主要用于配置文件，而不是像 JSON 那样在 Web 上传递的文件。

文件，而不是在 Web 上传递的文件，如 JSON。

键/值对

YAML 中的数据以键/值对的形式表示。键/值对通过冒号后跟空格来表示。

例如

在上面的示例中，Date 和 First Name 是键，2021-07-08 和 John 是值。

级别

级别由白色空格缩进指示，但我们不能使用制表符缩进。这是 YAML 和其他结构化格式之间最大的区别。XML 使用标签来增加一个级别，而在标签内有其他标签来增加另一个级别；因此，这增加了字符数量。在 JSON 中，花括号表示一个级别，占用了大量字符。在 YAML 中，只使用缩进，占用的字符较少。

XML

JSON

YAML

类型

YAML 中的类型根据上下文确定。

例如

在上述场景中，part_no 将被视为字符串，description 也将被视为字符串，price 将被视为浮点类型，quantity 将被视为整数。

注意：在 YAML 中，字符串不需要引号。有一个例外，如果某个内容被解释为数字或布尔值，则需要引号。

列表

• YAML 中的列表类似于 JSON。我们需要使用破折号来指示列表项。
• 我们不需要声明列表。

正如我们在上面的例子中观察到的，cart 是列表的名称，购物车中有两个列表项。两个列表项都用破折号表示。第一个列表项包含 4 个键/值对，而第二个列表项包含 5 个键/值对。

多行字符串

我们知道字符串不包含引号，因此我们需要特殊字符来处理多行字符串。以下是用于多行字符串的字符：

• |：它保留行和空格。
• >：它表示折叠行。

在上面的示例中，我们使用了 '|' 字符，因此其输出将与上面编写的相同。

输出

    YAML
   and JSON

如果我们使用 '>' 字符而不是 '|' 字符

 S: >
  YAML
     and JSON.

输出

YAML 和 JSON

Swagger 的历史

• 历史上，Swagger 是创建 API 定义文件的规范。
• 当新版本发布时，即 Swagger 2.0，该规范成为 Open API 规范 (OAS)。
• 现在，Swagger 不再是规范，而是使用 Open API 规范 (OAS) 的工具集合。
• 许多人将 OAS 称为 Swagger，但技术上并非如此。

Open API Initiative (开放 API 倡议)

• Open API Initiative 是由行业专家联盟创建的组织。
• 它致力于创建、发展和推广一种供应商中立的 API 描述格式。
• 它负责 Open API 规范，但不负责使用它的任何工具。

在理解 Swagger 之前，我们将首先理解什么是 Open API 规范？

什么是 Open API 规范？

最初，它被称为 Swagger 规范，后来更名为 Open API 规范。Open API 规范是一种规范，其中规范是一套定义如何做某事的规则。因此，Open API 规范是一套规则，它描述了如何用一种语言指定我们的 RESTful API。无论 API 使用什么技术，例如 JAVA、PHP、.NET，或其他什么，我们都希望我们的 API 能够被其他开发人员轻松使用。为了正确理解 API，我们应该了解关于 API 的所有以下信息：有哪些可用的端点，如 /customers、/employees、/orders 等，每个端点有哪些可用操作，如 GET、PUT、POST、DELETE 等，我们的 API 暴露的每个端点有哪些可用操作？要传递什么参数及其数据类型？API 将返回什么及其数据类型，使用什么身份验证方法？我们希望我们的外部世界甚至我们的内部客户都能了解我们的 API，而无需共享源代码。因此，必须有一些规则和标准，我们应该遵循来描述 API，并且每个人都将遵循相同的规则并以相同的方式描述他们的 API。在这里，Open API 规范发挥作用，它只是定义了一套规则，规定了如何描述 RESTful API。它们有描述 RESTful 服务各个方面的规则。有一些规则规定了 API 的可用端点。同样，也有规定每个端点操作的规则，基本上是针对所有方面都有规则，例如，针对参数、数据类型、返回值、身份验证方法等。Open API 规范还可以定义为一种标准且与语言无关的方式来描述 RESTful API。其思想是创建一个遵循这些规则的文档，可以是 JSON 或 YAML 格式，该文档描述了您的整个 API，例如可用的端点、可用的操作、要传递的参数、返回值、数据类型和身份验证方法。

让我们看看如何构建一个 OAS 文件。

我们将考虑一个例子然后构建一个文件。假设公司名称是 javatpoint.com，API 服务是上传和共享照片。此处，API 基本 URL 是https://api.javatpoint.com/photo

以下是如何开始一个文件的示例。

在上面的代码中，Open API 规范在编写 Open API 规范之前调用 swagger: 2.0。下一步是编写关于文件本身的内容，这是通过键'info:'完成的。在 info 下，我们有字符串的版本和 API 的标题。在标题之后，API 的主机是 api.javatpoint.com，basepath 是 /photo，因为 url 是 api.javatpoint.com/photo。 方案列表，在本例中只有方案。

添加请求

让我们定义获取照片相册的请求。以下是将包含在请求中的信息：

• URL 端点
• HTTP 方法
• 路径参数
• 查询参数

让我们通过一个例子来理解查询参数。

Get https://api.javatpoint.com/photo/album?start=2021-05-01&end=2021-05-31

API 定义文件

它以 'paths' 键开头，它是键的列表。换句话说，我们可以说通过此 URL 的操作列表在 paths 键中分组。此键以 '/album' 开头，表示 URL 以 '/album' 结尾。返回一个或多个相册的方法使用 GET 方法，因此我们将其放在 '/album' 之后。get 方法有一系列参数。在上面的 YAML 中，列表以 '-' 开头，因为 API 定义文件有一个查询参数列表。列表具有键

• name：这是表示参数名称的键。
• in：这是将参数定义为基于查询的参数的键。
• required：在上面，此键的值为 false，表示它是可选字段。
• Type：这是定义参数类型的键。

现在我们检索特定 ID 的相册。假设检索特定相册的 URL 如下所示：

Get https://api.javatpoint.com/photo/album/12345

上面的 URL 将检索具有唯一 ID 12345 的特定 URL。让我们看一下定义。

在上面的 YAML 中，键定义为 /album/{id}，其中 id 定义在花括号内。这表示路径参数稍后将以名为 'id' 的名称定义。然后，我们有一个 get 方法，然后我们包含一个参数列表。此处我们只添加了一个名为 'id' 的列表项。'in' 的值为 path，表示它是路径参数，'required' 字段为 true，这在路径参数中始终如此，类型为整数。

什么是 Schema？

某些类型的请求需要额外数据，例如 POST、PUT 方法，这些方法称为 HTTP 方法。包含这些方法的正文称为请求正文。请求正文中的数据可以采用 JSON 或 XML 格式。

响应正文中表示的所有响应都可以采用 JSON 格式。此处，Schema 主要定义数据的结构。OAS schema 对象基于 JSON Schema 规范。数据的 Schema 决定了键/值对中的键是什么，值的类型是什么。Schema 中可以有很多级别。

$ref

$ref 是一个特殊的 OAS 键，表示该值是对 YAML 文件中某处的结构的引用。它很有用，因为这样我们可以避免 YAML 文件中有太多的缩进级别。

让我们通过一个例子来理解。

文件1

文件2

在 File1 中，我们在 schema 中定义了一个 $ref 键，其值为 '#/definitions/newAlbum'。我们创建了另一个名为 File2 的文件，其中定义了一个名为 'definitions' 的新键，它有一个名为 'newAlbum' 的另一个键，并且缩进结构反映在 File1 的 $ref 键中。

请求正文

请求正文包含在 parameters 键下定义的参数。以下是参数列表：

• name：它仅用于引用，但在文档中不显示。
• in：它有一个 'in' 键，设置为 body。
• required：这是一个通常设置为 true 的键。
• Schema：它有一个 schema 键而不是 type，该 schema 键有一个 $ref 键，并且 $ref 包含带引号的引用路径的值。

请求正文示例

上面的 YAML 是一个 POST 请求，其中包含 parameters 键。parameters 有一个名为 'album' 的列表。它有一个包含 $ref 键的 schema，该 $ref 键指向 schema 的预期路径。

Schema 部分

• 在 schema 部分，我们在文件末尾创建一个名为 definitions 的键。
• 然后，我们添加一个级别并为其命名，名称来自 $ref 值。
• 添加一个 properties 键。
• 对于 JSON 中的每个顶级元素，添加一个以其名称命名的键。
• 添加一个 type 键来指示它是哪种类型。
• 添加其他键以获取其他数据。

Schema 示例

在上面的 schema 中，我们可以观察到 newAlbum 有两个名为 name 和 date 的属性，并且两者都是 string 类型。

注意：键/值的 值不必是简单类型；我们可以添加其他对象作为值。要做到这一点，我们需要按照以下步骤操作：

• 首先，我们需要使用 object 类型。
• 然后，我们需要添加一个带有 properties: 的新级别，然后像以前一样继续。

在上面的 schema 中，我们可以观察到 schema 是 object 类型，后跟 properties 键。properties 键有两个属性，名为 first name 和 last name，类型为 string。

上面的文件有很多缩进。为了解决这个问题，我们可以在 definition 中使用 $ref。让我们通过一个例子来理解。

在上面的情况中，author 键有一个 $ref 键，它指向 person 键的 definition 路径。person 有 properties 键，其中有两个名为 first name 和 last name 的属性。

Schema 数组

• 我们也可以添加数组。
• 我们使用 array 类型。
• 然后，我们添加一个 items 键。
• 并定义类型和其他任何属性。

声明 schema 数组的语法是

在上面的示例中，marks 是一个数组，其中 items 类型为 string。

带 $ref 的 Schema 数组

对于复杂类型，我们对数组项使用 $ref。让我们通过一个例子来理解。

在上面的 schema 中，photos 是类型为 array 的键，它具有指向 photo 键的列表项。photo 键有三个属性，即 id 类型为 integer，longitude 类型为 number，latitude 类型为 number。

什么是 Swagger？

Swagger 为 Open API 规范文件提供了一个编辑器。要访问 swagger 编辑器网站，请访问以下链接：

http://editor2.swagger.io

Swagger 是用于生成交互式文档的流行工具之一。它为用户生成交互式 API，以便他们能够更快地理解 API。

Swagger 和 Open API 规范之间的区别

OpenAPI 是一个规范，而 Swagger 是用于实现该规范的工具。OpenAPI 规范的开发由 OpenAPI Initiative 完成，该倡议涉及来自世界不同地区的 30 多个组织。Smartbear Software 是开发 Swagger 工具的公司，也是 OpenAPI Initiative 的成员，因此也为规范的开发做出了贡献。

Swagger 是与广泛使用的工具相关联的工具，用于实现 OpenAPI 规范。Swagger 工具集包括在 API 生命周期不同阶段使用的开源、免费和商业工具。

以下是 Swagger 中包含的工具：

1. Swagger Editor：这是一个允许我们在浏览器中以 YAML 格式编辑 Open API 规范并实时预览文档的工具。
2. Swagger UI：这是一个由 HTML、Javascript 和 CSS 资源组成的工具集，允许我们动态生成漂亮的文档。
3. Swagger Codegen：它允许我们自动生成 API 客户端库、服务器存根和文档。
4. Swagger core：它包含用于创建、使用和处理 API 定义的 Java 相关库。
5. Swagger Inspector：这是一个 API 测试工具，允许您验证您的 API 并从现有 API 生成 OpenAPI 定义。

Swagger 中的文档

什么是自动生成的文档？

Swagger 等工具获取 OAS 文件并从中生成 HTML 文档，以便可以在网上更新。只要 OAS 文件保持最新，文档就可能比手动编写文档更准确。它还允许您直接在文档中试用请求，从而帮助开发人员编写代码。

我们将使用 Swagger Editor 设计和记录 RESTful API。

假设我们有一个 Student API 和资源，我们将根据 Query 参数获取学生姓名。在 Query 参数中，我们将传递学生姓名。在此 API 中，我们还将有一个 POST 操作，通过此 API 添加新学生。我们还将执行 GET 操作，该操作通过路径参数检索数据。

在浏览器中打开 Swagger 编辑器，如下所示：

这是一个非常智能的工具，它提供了大量的建议。当我们按下 ctrl+space 时，它会提供很多建议。

首先，我们使用 openapi 版本 3.0.0，如下所示：

现在我们将 API 的基本信息添加到元数据中，如下所示：

上面，我们添加了基本信息，例如 API 的标题、API 的描述和 API 的联系人。

接下来我们要添加服务器。我们可以通过添加每个服务器的 URL 来添加多个服务器。

添加服务器后，我们将添加路径。在路径内，我们需要在路径中添加资源以及操作。

上面，我们添加了 Student 资源及其描述。然后，我们包含了 get 操作。首先，我们提供了 get 方法的描述，然后我们包含了将在 Get 方法中传递的参数。我们传递了基于查询的参数，名为 Studentname，下一个参数是必需的，其值为 true，因为 studentname 参数在 Get 方法中是强制的。现在我们将表示基于查询的参数的 schema。在 schema 中，我们包含了参数的类型和示例。在此案例中，我们指定了 Query parameter。

现在我们将指定下一个级别应该是什么响应。我们首先提到 responses:，然后在 responses 中，我们需要指定我们显示响应的 http 代码。在真实场景中，我们应该涵盖所有主要响应代码。此处，我们将指定 happy scenario，即 200 代码表示成功响应。在响应代码之后，我们将指定响应代码的描述，'Successful response'。然后，我们将指定内容的格式，即 'application/json' 表示内容将以 json 格式表示。一旦包含内容格式，我们就需要指定 schema。由于这是响应，因此将执行 get 操作。操作的类型是 array，并且 array 有一个项目列表，因此我们将 items 指定为键。items 有 properties 键。正如我们在上面的截图中所观察到的，它包含三个属性，即 Student id 类型为 integer，Student name 类型为 string，Studentremarks 类型为 string。

下一个操作是我们必须执行的 POST 操作。首先，我们在编辑器中指定 post 方法，然后我们添加 POST 方法的描述“Add a new Student”。在 POST 方法内部，我们需要指定 requestBody，因为它期望在 student 对象中以 JSON 格式的 requestBody。在 content 中，我们添加内容的格式，即 'application/json'。由于这是一个 POST 操作，因此我们期望得到 object 类型而不是 array 类型。POST 操作中的所有属性将与 GET 操作相同。添加完所有属性后，我们将添加 responses 键，在其中添加 201 代码，表示 happy scenario。在 responses 键下，我们添加响应代码的描述，即 'Record successfully added'。

到目前为止，我们正在使用查询参数获取学生资源。假设我们想使用路径参数获取学生资源，那么我们需要在路径中添加以下代码：

下面的文件是完整的 API 定义文件：

输出

上面的截图显示 API 执行了三个操作。第一个操作是接受学生姓名的 GET 操作，第二个操作是接受 JSON 格式的 requestBody 的 POST 操作，第三个操作是接受名为 'id' 的路径参数的 GET 操作。