Swagge不仅只有API，还有这些强大功能

最新推荐文章于 2024-09-19 19:36:22 发布

怪咖@

最新推荐文章于 2024-09-19 19:36:22 发布

阅读量4.1k

点赞数 2

分类专栏： # Swagger 文章标签： java 编辑器

本文链接：https://blog.csdn.net/weixin_43888891/article/details/123618643

版权

Swagger 专栏收录该内容

1 篇文章 2 订阅

订阅专栏

Swagger 提供了一系列用于生成、可视化和维护 API 文档的解决方案，从而消除了 API 文档中的手动工作。

一、Swagger简介

官网：https://swagger.io/irc/
Swagger就是一个用于接口文档的一个工具框架，现在普遍开发都是前后端分离，也就是我们常说的细分化，专业的人干专业的事。那么问题来了，前后端分离是分离了，但是他们肯定要有交接，交接就是我们所说的对接口。

像现在比较流行的接口文档工具其实有很多，例如showdoc、YApi等等。这些其实就是提供了一个平台（当然也可以在自己服务器搭建一套进行使用），我们可以注册自己的账号然后在上面添加接口文档，添加完接口之后分享给前端人员。

而swagger可以在controller当中通过添加注解自动生成接口文档。
好处：通过代码生成接口文档，可以实时保证接口文档是最新的。

现在的话，除一些老前后端分离项目没用swagger，新项目现在普遍都用的swagger。

二、Swagger功能产品

swagger其实还有很多产品，而不仅仅通过注解生成接口文档。

实际上我们都知道，前后端分离开发，我们作为后端需提前的去设计API。但是我们可以发现，我们在开发过程中订立的api的寿命其实不怎样长，这是一件非常严重的事情，基本是就是联调过后就不再维护了。

因此丝袜哥为我们提供了另外一种比较优雅的方式，那就是你先订立契约，然后在去用生成的契约也就是接口文档去生成代码，这是非常好的一种实践方式。

2.1.Swagger UI

Swagger UI 允许任何人——无论是你的开发团队还是你的最终消费者——在没有任何实现逻辑的情况下可视化 API 资源并与之交互。它是根据您的 OpenAPI（以前称为 Swagger）规范自动生成的，其可视化文档使后端实现和客户端使用变得容易。

在线文档：https://petstore.swagger.io/?_ga=2.44687840.512159656.1647772580-2111599552.1639917235#/
在这里插入图片描述

2.2.Swagger Hub

SwaggerHub就是swagger提供的一个编译器，相当于通过swagger固定语法编码进行写接口文档。可用于托管 API 文档的。
在这里插入图片描述

2.3.Swagger Codegen

Swagger Codegen是一个开源的代码生成器，可以从您的 API 设计中自动生成 20 多种语言的 API 样板代码。Swagger Codegen的源码可以在Github上找到。

官方文档中也提出了SwaggerHub用于协作API开发，Swagger Codegen用于个人开发使用。意思就是SwaggerHub是写接口文档用的，而Swagger Codegen可以通过接口文档生成指定语言的代码。

github地址：https://github.com/swagger-api/swagger-codegen

2.4.Swagger editor

Swagger Edit是用来编辑接口文档的小程序，简单易用。在官网上分为在线编辑和下载代码线下编辑，两种编辑方式。Swagger是通过YAML来定义你的接口规范。可以通过接口文档帮你生成不同框架的服务端和客户端，方便你mock和契约测试。最后导出JSON格式的API规范，通过Swagger UI对外发布。下图就是Swagger Edit界面：

在线版的：https://editor.swagger.io/
该网站支持根据在线API生成各种语言的代码。

在这里插入图片描述

2.5.Swagger Inspector

swagger inspetor是API测试和生成文档的工具。
相当于是可以通过访问接口，拿到请求的数据，然后根据请求生成api文档。并且可以将文档放到Swagger Hub。
说明：

尚未开源
B/S架构，浏览器中完成API测试
无法本地搭建，只能使用swagger云服务
可以测试HTTP/HTTPS/webservice
如果有swaggerhub账号（可以用github账号替代），可以保存测试记录到云服务中，随时随地登录可查看
测试记录可生成API文档保存到swaggerhub中

官网地址：https://swagger.io/tools/swagger-inspector/

2.6.Swagger ReadyAPI

ReadyAPI 是一个易于使用的无代码 API 测试平台，旨在简化您的测试工作流程。

2.7.Swagger AlertSite

使用 AlertSite for OAS 从您的 OpenAPI 规范 (OAS) 开始监控 API 可用性、速度和功能。自动创建监视器并立即跟踪 API 行为，以确保一切在生产中顺利运行。（未开源）

三、什么是 OpenAPI？

OpenAPI 规范于 2015 年在 OpenAPI 倡议下捐赠给 Linux 基金会。该规范可用于创建RESTful 接口，通过有效地映射与其关联的所有资源和操作来轻松开发和使用 API。

OpenAPI 规范（以前称为 Swagger 规范）是 REST API 的 API 描述格式。可以理解为就是编写接口文档的固定语法。OpenAPI 文件允许您描述整个 API。

API 规范可以用 YAML 或 JSON 编写。该格式易于学习，对人类和机器来说都是可读的。

Swagger是一组围绕 OpenAPI 规范构建的开源工具，可以帮助您设计、构建、记录和使用 REST API。主要的 Swagger 工具包括：

Swagger Editor – 基于浏览器的编辑器，您可以在其中编写 OpenAPI 规范。
Swagger UI – 将 OpenAPI 规范呈现为交互式 API 文档。
Swagger Codegen – 从 OpenAPI 规范生成服务端代码和客户端代码。

官网介绍：https://swagger.io/docs/specification/about/

四、什么是 REST API？

REST API是一种设计的风格，而OpenAPI是描述接口文档的一种语言规范。

在目前主流的三种Web服务交互方案中，REST相比于SOAP（Simple Object Access protocol，简单对象访问协议）以及XML-RPC更加简单明了，无论是对URL的处理还是对Payload的编码，REST都倾向于用更加简单轻量的方法设计和实现。值得注意的是REST并没有一个明确的标准，而更像是一种设计的风格。

RESTFUL特点包括：

每一个URI代表1种资源；
客户端使用GET、POST、PUT、DELETE4个表示操作方式的动词对服务端资源进行操作：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源；
通过操作资源的表现形式来操作资源；
资源的表现形式是XML或者HTML；
客户端与服务端之间的交互在请求之间是无状态的，从客户端到服务端的每个请求都必须包含理解请求所必需的信息。（往往都是code、data、message）

举例：比如/user接口，一般接口都会存在crud，那么就利用请求方式get、post、delete、put来区分crud，但是请求的url是一样的。

那么他这样做的好处是什么？

具有扩展性强、结构清晰的特点。假如你不这么做，可能修改接口有的写的是putUser，换个开发人员对修改接口是updateUser，再换个开发人员modifiUser。这样就会导致不统一、不直观，一个项目会有多个修改接口，这样就会导致url命名很乱。

五、什么是 RPC

RPC是远程过程调用（Remote Procedure Call）的缩写形式。

比如现在我要调用一个方法，是获取到订单信息，那么在传统项目中，一般是直接调用的，如下：

在这里插入图片描述
现在，基于高性能和高可靠等因素的考虑，你决定将系统改造为分布式应用，将很多可以共享的功能都单独拎出来，比如上面说到的订单信息，你单独把它放到一个服务里头，让别的服务去调用它。所以就变成了下面这样：
在这里插入图片描述
这下问题来了，服务A里头并没有 OrderServiceImpl 这个类，那它要怎样调用服务B的 OrderServiceImpl 的 get 方法呢？这就可以用到 RPC 框架了，所以我们知道，RPC 框架主要用来解决两个问题：

解决分布式系统中，服务之间的调用问题。
远程调用时，要能够像本地调用一样方便，让调用者感知不到远程调用的逻辑。

RPC请求流程：

RPC 样式的 Web 服务客户端将一个装满数据的信封（包括方法和参数信息）通过 HTTP 发送到服务器。
服务器打开信封并使用传入参数执行指定的方法。方法的结果打包到一个信封并作为响应发回客户端。
客户端收到响应并打开信封。每个对象都有自己独特的方法以及仅公开一个 URI 的 RPC 样式 Web 服务，URI 表示单个端点。它忽略 HTTP 的大部分特性且仅支持 POST 方法。