下篇：Knife4j-的使用(详细教程)
作为后端开放人员，最烦的事就是自己写接口文档和别人没有写接口文档，不管是前端还是后端开发，多多少少都会被接口文档所折磨，前端会抱怨后端没有及时更新接口文档，而后端又会觉得编写接口文档太过麻烦。Swagger 可以较好的接口接口文档的交互问题，以一套标准的规范定义接口以及相关的信息，就能做到生成各种格式的接口文档，生成多种语言和客户端和服务端的代码，以及在线接口调试页面等等。只需要更新 Swagger 描述文件，就能自动生成接口文档，做到前端、后端联调接口文档的及时性和便利性。
官网：https://swagger.io/
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
Swagger 的优势
- 支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
- 提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。
通过在项目中引入 Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。
在配置文件 目录下，添加 swagger 的配置文件
这个时候 Swagger 已经算是整合到项目之中了，可以启动下服务，输入： （这里我的项目端口是 8868 ，项目路径是 /mike，所以我打开的文档地址为 ）即可查看 swagger 文档。
可以看到 Swagger 文档中大概有这四类信息
- 组
- 基本信息
- 接口信息
- 实体类信息
2.1 配置基本信息
Swagger 有自己的实例 Docket，如果我们想要自定义基本信息，可以使用 docket 来配置 swagger 的基本信息，基本信息的设置在 这个对象中。
Swagger 默认的基本信息展示
ApiInfo 中默认的基本设置
- title：Api Documentation
- description：Api Documentation
- version：1.0
- termsOfServiceUrl：urn:tos
- contact：无
- license：Apache 2.0
- licenseUrl：http://www.apache.org/licenses/LICENSE-2.0
配置文件添加以下内容：
重启服务，打开 Swagger 文档，基本信息改变如下所示：
2.2 配置接口信息
默认情况下，Swagger 是会展示所有的接口信息的，包括最基础的 相关的接口
有时候我们希望不要展示 相关的接口，或者是说这想要显示某些接口，比如说： 下的接口，由该怎么去实现呢？这个时候就需要设置
可根据自己的需求去设置对应的配置，这里我就不再一一赘述了，以上是我所设置的配置，重启服务，打开 Swagger 文档，接口信息改变如下所示：
可以看到之前 相关的接口已经没有了
2.3 配置分组信息
Swagger 默认只有一个 default 分组选项，如果没有设置，所有的接口都会显示在 `分组下，如果功能模块和接口数量一多，就会显得比较凌乱，不方便查找和使用。
swagger 文档中组名默认是 ，可通过
修改后：
如果需要配置多个组的话，就需要配置多个 ，这里我就简单写两组，代码如下：
重启服务，打开 Swagger 文档，接口信息改变如下所示：
组名为 的文档中只有 相关的接口信息
组名为 的文档中只有 相关的接口信息
在开发或者测试环境下，我们开启 swagger 会方便前端和后端的交互，但是如果在生产环境下也开启 swagger 的话，是会将接口暴露出去的，有极大风险，如何让 swagger 根据不同的环境来决定是否开启？
这里我准备了四个项目的配置文件，、、 三个环境的配置文件仅是端口上的不同
- application.yml -------------------------- 全局配置文件
- application-dev.yml -------------------- 开发环境配置文件
- application-test.yml -------------------- 测试环境配置文件
- application-pro.yml -------------------- 生产环境配置文件
内容如下，用于指定选择的环境：
可以通过代码判断此时是在什么环境：、、，如果是在 生产环境，则关闭 swagger。
在 全局配置文件中环境指向 时，是可以打开 swagger 的
如果我将 全局配置文件中环境指向 时，就不能打开 swagger 了，提示
之前有说 Swagger 会将接口请求或者相应的实体类信息展示在 下的，比如我 下有一个接口如下所示：
它的请求体是 ，响应是 ， 展示这两个实体类信息如下：
前端可通过看这个 知道后端定义实体类的信息。
@ApiModel
该注解是作用于类上面的，是用来描述类的一些基本信息的。
相关属性：
- ：提供类的一个备用名，如果不设置，默认情况下将使用 class 类的名称
- description：对于类，提供一个详细的描述信息
- parent：这个属性用于描述的是类的一些父类信息
- discriminator：这个属性解释起来比较麻烦，因为这个类主要体现在断言当中
- subTypes：可以通过这个属性，指定我们想要使用的子类
譬如：这个为给 这个类添加该注解
可以看到这里的名字从 变成 了
@ApiModelProperty
它的作用是添加和操作属性模块的数据。
该注解的使用详情可参见博客：@ApiModelProperty注解的用法
这里我还是以 类为例，为该类的属性添加说明
可以看到这里对该字段有一个备注说明。
@ApiOperation
该注解用来对某个方法/接口进行描述
该注解的使用详情可参见博客：Swagger @ApiOperation 注解详解
这里我以 下的接口为例：
可以看见该接口就多了对其的描述信息。
@ApiParam
该注解使用在方法上或者参数上，字段说明，表示对参数的添加元数据（说明或者是否必填等）
相关属性：
- name：参数名
- value：参数说明
- required：是否必填
这里我以 下的接口为例：
这里会展示请求参数的备注信息，以及是否必填等。
使用 swagger 除了让前后端交互变得方便，也让接口的请求变得简单，只需要填写好请求所需要的参数信息，便可直接发起请求。
比如说接口
点击
设置好请求所需的参数，点击 执行
就能看到接口响应的结果了
接口 也差不多
有时候我们的接口是需要获取请求头信息的，这样的话就还需要在 swagger 配置中添加请求头的配置。
比如接口：
可以看到这个接口已经可以去设置请求头了，调用接口
后端也能获取到。
以下是我这个项目所编写的代码
链接：百度网盘
提取码：na2o
下篇：Knife4j-的使用(详细教程)
到此这篇swagger使用教程（swagger怎么使用）的文章就介绍到这了,更多相关内容请继续浏览下面的相关推荐文章，希望大家都能在编程的领域有一番成就！
版权声明：
本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如若内容造成侵权、违法违规、事实不符，请将相关资料发送至xkadmin@xkablog.com进行投诉反馈，一经查实，立即处理！
转载请注明出处，原文链接：https://www.xkablog.com/rfx/81884.html