📌  相关文章
📜  Swagger文档格式简介

📅  最后修改于: 2021-01-11 05:58:58             🧑  作者: Mango

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标题，termOfServices和URL。
  • host：它指定我们托管服务的主机。
  • basePath：在端口号之后和API之前的URI中使用。
  • 标签：我们可以为资源分配标签。它用于将资源分为多个类别。
  • 路径：它指定了我们要公开的资源的路径以及可以对这些资源执行的不同操作。
  • 定义：它包含我们在API中使用的不同元素。

我们将详细讨论信息，路径和定义这三个元素。

让我们看看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"}},
  • 描述：它包含API的高级信息。
  • 版本：它显示了我们要公开的API版本。
  • title：指定API的标题。
  • termOfService：它指定服务期限(如果有)。
  • 联系人：它指定一个人的联系方式(如果有)。
  • 许可证：它指定默认许可证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":{"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请求外，我们还有作为请求正文的一部分发送的参数。我们接受输入类型的用户作为请求的主体。

展开“ / 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 。在delete方法内部，有一个名为id的参数。在发布请求中，我们将路径中接受的此ID放入内容作为请求正文的一部分。

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

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

有两种向客户公开文档的方法：

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