Swagger 文档格式简介

在本节中，我们将详细介绍生成的文档。 Swagger 是一个用于记录 REST API 的规范。 它指定了描述 REST Web 服务的格式（URL、方法和表示）。 它还提供了从应用程序代码生成/计算文档的工具。

作为应用程序开发人员，我们使用框架编写 Web 服务，Swagger 扫描应用程序代码，并在 URL 上公开文档。 客户端可以使用此 URL 并了解如何使用 REST Web 服务：在哪个 URL 上调用哪个 HTTP 方法，发送哪个输入文档，期望哪个状态代码等。

我们将了解 Swagger 文档的内容。 当我们仔细查看 Web API 的文档时，我们在文档的开头看到一些重要的元素，如下图所示。

以下是 Swagger 文档中存在的重要 Swagger 元素。

• swagger: 它指定了我们正在使用的 Swagger 的版本规范。
• info: info 选项卡包含有关 API 的信息，例如描述、API 版本、API 标题、服务条款和 URL。
• host: 它指定了我们托管服务的主机。
• basePath: 它在端口号之后和 API 之前用于 URI 中。
• tags: 我们可以为我们的资源分配标签。 它用于将资源分组到多个类别中。
• paths: 它指定了我们公开的资源的路径以及可以在这些资源上执行的不同操作。
• definitions: 它包括我们在 API 中使用的不同元素。

我们将详细讨论三个元素：info、paths 和 definitions。

让我们看看 info 元素里面是什么

• description: 它包含 API 的高级别信息。
• version: 它显示了我们公开的 API 版本。
• title: 它指定 API 的标题。
• termOfService: 它指定了服务条款（如果有）。
• contact: 它指定了联系人的详细信息（如果有）。
• license: 它指定了默认许可证 Apache 2.0。

让我们展开 path 元素。 它包含我们正在公开的所有路径。

两个最重要的资源是“/users”和“/users/{id}”。 这些资源公开了用户组。 让我们逐个展开这两个资源。

展开“/users”资源

上面的资源包含可以执行的两个操作 get 和 post。 我们可以使用 get 操作来检索所有用户，并使用 post 操作来发布用户。

在 get 操作中，我们获得了所有存在的响应状态。 响应状态 200 表示成功创建用户，401 表示未经授权的资源访问，404 表示未找到，403 表示禁止访问。 当我们查看状态 200 时，存在一个模式定义。 模式定义表明我们正在发送用户数组作为响应。 用户数组存在于 definitions 中。 同样，我们也可以展开 definitions 标签以查看用户的定义。

除了 POST 请求之外，我们还有一些参数作为请求正文的一部分发送。 我们接受输入类型user作为请求的正文。

展开“/users/{id}”资源

/users/{id} 资源允许两个操作 get 和 delete。 在 delete 方法中，有一个名为 id 的参数。 此 id 是我们在路径中接受的，而在 post 请求中，我们将内容作为请求正文的一部分放置。

定义定义了正在使用的不同类型的对象。 这些定义用于每个资源公开的不同操作中。 当我们对 /users 执行 get 操作时，它会返回用户列表。 此用户的资源会发送回以获取资源 /user/{id} 的操作，并且用户的资源包含其他链接。 链接的定义也存在于用户类型的资源中。

链接包含 rel 和 href。 rel 全都是 -users，href 是指向特定资源的链接。

有两种方法可以向客户端公开文档

• 从 https://:8080/v2/api-docs 下载 JSON 格式的文档，并将其发送给客户端。
• 共享 Swagger UI 的链接 https://:8080/swagger-ui.html。 这是一个描述所有准备公开的操作的 UI。