Spring boot教程-Swagger 文档格式介绍
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 元素的内容：
"info":{"description":"Api Documentation","version":"1.0","title":"Api Documentation","termsOfService":"urn:tos","contact":{},"license":{"name":"Apache 2.0","url":"http://www.apache.org/licenses/LICENSE-2.0"}},
- description： 它包含 API 的高级信息。
- version： 它显示我们正在公开的 API 版本。
- title： 它指定 API 的标题。
- termOfService： 它指定服务条款，如果有的话。
- contact： 它指定联系人的详细信息，如果有的话。
- license： 它指定默认的 Apache 2.0 许可证。
让我们展开 path 元素。它包含我们正在公开的所有路径。
paths: {
/error: {-}
/hello-world: {-}
/hello-world-bean: {-}
/hello-world-internationalized: {-}
/hello-world/path-variable/{name}: {-}
/users: {-}
/users/{id}: {-}
},
最重要的两个资源是 "/users" 和 "/users/{id}"。这些资源公开了用户组。让我们逐个展开这两个资源。
展开 "/users" 资源：
"/users":{"get":{"tags":["user-resource"],"summary":"retriveAllUsers","operationId":"retriveAllUsersUsingGET","produces":["*/*"],"responses":{"200":{"description":"OK","schema":{"type":"array","items":{"$ref":"#/definitions/User"}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false},"post":{"tags":["user-resource"],"summary":"createUser","operationId":"createUserUsingPOST","consumes":["application/json"],"produces":["*/*"],"parameters":[{"in":"body","name":"user","description":"user","required":true,"schema":{"$ref":"#/definitions/User"}}],"responses":{"200":{"description":"OK","schema":{"type":"object"}},"201":{"description":"Created"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false}},
上述资源包含两个操作 get 和 post，可以执行这两个操作。我们可以使用 get 操作检索所有用户，使用 post 操作发布用户。
在 get 操作内部，我们获得了所有存在的响应状态。响应状态 200 表示用户成功创建，401 表示资源未经授权访问，404 表示未找到，403 表示禁止访问。当我们查看状态 200 时，有一个模式定义。模式定义显示我们将作为响应发送的用户数组。用户数组在定义中存在。类似地，我们还可以展开 definitions 标签，查看用户定义的定义。
除了 POST 请求外，我们还有作为请求主体一部分发送的参数。我们接受一个名为 user 的输入类型作为请求的主体。
展开 "/users/{id}" 资源：
"/users/{id}":{"get":{"tags":["user-resource"],"summary":"retriveUser","operationId":"retriveUserUsingGET","produces":["*/*"],"parameters":[{"name":"id","in":"path","description":"id","required":true,"type":"integer","format":"int32"}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/Resource«User»"}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Not Found"}},"deprecated":false},"delete":{"tags":["user-resource"],"summary":"deleteUser","operationId":"deleteUserUsingDELETE","produces":["*/*"],"parameters":[{"name":"id","in":"path","description":"id","required":true,"type":"integer","format":"int32"}],"responses":{"200":{"description":"OK"},"204":{"description":"No Content"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}},"deprecated":false}}},
/users/{id} 资源允许两个操作 get 和 delete。在删除方法内部，存在一个名为 id 的参数。我们在路径中接受此 id，而在 post 请求中，我们将内容作为请求的主体部分。
定义定义了不同类型的对象。这些定义在每个资源公开的不同操作中使用。当我们在 /users 上执行 get 操作时，它返回用户列表。这个用户资源发送回用户资源的 get 操作，而用户资源中还包含了额外的链接。用户类型资源中也存在链接的定义。
链接包含 rel 和 href。rel 是 -users，而 href 是指向特定资源的链接。
有两种方法将文档公开给客户端：
- 从
http://localhost:8080/v2/api-docs下载文档为 JSON 并将其发送给客户端。 - 共享 Swagger UI 的链接
http://localhost:8080/swagger-ui.html。这是一个 UI，描述了所有已准备好公开的操作。
