SpringBoot学习之整合Swagger

古城微笑少年丶 2024-03-27 19:00 79阅读 0赞

## Swagger介绍 ##

### 1.什么是Swagger ###

作为后端程序开发，我们多多少少写过几个后台接口项目，不管是编写手机端接口，还是目前比较火热的前后端分离项目，前端与后端都是由不同的工程师进行开发，那么这之间的沟通交流通过接口文档进行连接。但往往伴随很多问题，后端程序员认为编写接口文档及维护太花费时间精力，前端的认为接口文档变动更新不及时，导致程序之间相互调用出行问题。那么能简化接口文档的编写直接自动生成吗？当然能！如是乎Swagger这种接口文档在线自动生成工具便孕育而生。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

### 2.Swagger优点 ###

*  代码变，文档变。只需要少量的注解，Swagger 就可以根据代码自动生成 API 文档，很好的保证了文档的时效性。
 *  跨语言性，支持 40 多种语言。
 *  Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程。
 *  还可以将文档规范导入相关的工具（例如 Postman、SoapUI）, 这些工具将会为我们自动地创建自动化测试。

## SpringBoot中整合Swagger ##

### 1.基础环境构建 ###

首先搭建一个基础的SpringBoot项目，导入以下Swagger启动器

<dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter<artifactId>
        <version>3.0.0</version>
    </dependency>

编写一个用于测试的controller

@RestController
    public class HelloController {
    
        @PostMapping(value = "/hello")
        public String hello(){
            return "hello";
        }
    }

编写Swagger的配置类

@Configuration
    @EnableOpenApi
    public class SwaggerConfig {
    }

运行启动输入地址：http://localhost:8080/swagger-ui/index.html

可以看到Swagger接口文档页面，说明基本配置环境成功！

![图片][f2cf311a1158a0f2d97b6f70c7605e40.png]

> 注意事项：  
> Swagger3.0版本的地址是http://localhost:8088/swagger-ui/index.html，2.x版本中访问的地址的为http://localhost:8088/swagger-ui.html

### 2.配置Swagger ###

配置Swagger首先需要构建其Bean实例 `Docket`对象，在刚刚创建的`SwaggerConfig` 配置类中创建一个Docket

@Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo());
    }

`Docket(DocumentationType.OAS_30)` ,我们这里选择的参数是 `DocumentationType.OAS_30`,这是一个Swagger实例的接口文档版本，我们这里是3.0，所以选择用 `OAS_30`，其他的类型还有如下几种，分别对应着Swagger历史版本

public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2");
        public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0");
        public static final DocumentationType OAS_30 = new DocumentationType("openApi", "3.0");

构建Docket需要创建 `ApiInfo` 实例

private ApiInfo apiInfo(){
        // 作者信息
        Contact contact = new Contact("TIOXY", "https://www.cnblogs.com/tioxy/", "1369773052@qq.com");
    
        return new ApiInfo(
                "Tioxy的接口文档",
                "项目描述",
                "1.0",
                "https://www.cnblogs.com/tioxy/",
                contact,
                "Apache 2.0",
                "http://www.apache.org/licenses/LICENSE-2.0",
                new ArrayList());
    }

`ApiInfo` 主要作用是构建我们接口文档的页面显示的基础信息，展示如下位置

![图片][fe33c76561908b0bff34375310006ee2.png]

### 3.配置扫描接口及开关 ###

构建Docket时通过 `select()` 方法配置扫描接口。Docket的完整代码如下：

@Bean
    public Docket docket(Environment environment){
        // 设置显示的Swagger环境
        Profiles dev = Profiles.of("dev");
        // 获取项目环境
        boolean flag = environment.acceptsProfiles(dev);
    
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                // 配置Api文档分组
                .groupName("TIOXY")
                // enable()是否启用Swagger，默认是true
                .enable(flag)
                .select()
                // RequestHandlerSelectors,配置要扫描接口的方式
                // basePackage指定要扫描的包
                // any()扫描所有，项目中的所有接口都会被扫描到
                // none()不扫描
                // withClassAnnotation()扫描类上的注解
                // withMethodAnnotation()扫描方法上的注解
                .apis(RequestHandlerSelectors.basePackage("com.tioxy.controller"))
                // paths()过滤某个路径
                .paths(PathSelectors.any())
                .build();
    }

*  `groupName("TIOXY")`：表示此Docket实例的名字，也就是接口文档页面右上角选择的实例名，实际开发中我们是多人开发，对应的就是多个Docket实例
 *  `enable(flag)`：`enable()`是否启用Swagger，默认是true

我们这里使用的是动态的配置是否启用Swagger，通过 `Environment` 来获取此时运行的项目环境名称，如果是 `dev`,则定义一个flag，来动态的设置是否启用

### 4.实体类配置 ###

新建一个User实体类

@ApiModel("用户实体")
    public class User {
       @ApiModelProperty("用户名")
       public String username;
       @ApiModelProperty("密码")
       public String password;
    }

只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

@RequestMapping("/getUser")
    public User getUser(){
       return new User();
    }

![图片][c5b434dc749c1393b79631466063621e.png]

### 5.常用注解 ###

我们也可以在接口上添加注释说明，方便我们在接口文档中解释说明接口的信息，例如接口的作用、参数说明等，方便调用者使用

<table> 
 <thead> 
  <tr> 
   <th>Swagger注解</th> 
   <th>简单说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>@Api(tags = "xxx模块说明")</td> 
   <td>作用在模块类上</td> 
  </tr> 
  <tr> 
   <td>@ApiOperation("xxx接口说明")</td> 
   <td>作用在接口方法上</td> 
  </tr> 
  <tr> 
   <td>@ApiModel("xxxPOJO说明")</td> 
   <td>作用在模型类上：如VO、BO</td> 
  </tr> 
  <tr> 
   <td>@ApiModelProperty(value = "xxx属性说明",hidden = true)</td> 
   <td>作用在类方法和属性上，hidden设置为true可以隐藏该属性</td> 
  </tr> 
  <tr> 
   <td>@ApiParam("xxx参数说明")</td> 
   <td>作用在参数、方法和字段上，类似@ApiModelProperty</td> 
  </tr> 
 </tbody> 
</table>

[f2cf311a1158a0f2d97b6f70c7605e40.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/c9e10da3a7234f3287a0d83485330db4.png
[fe33c76561908b0bff34375310006ee2.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/657cdfd885094de28e9bdb59ea239460.png
[c5b434dc749c1393b79631466063621e.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/03/13/88326469823440bc917bbcbac7384985.png