SpringBoot中整合Swagger

以你之姓@ 2021-08-29 14:13 405阅读 0赞

## SpringBoot中整合Swagger ##

Swagger就是一个API接口文档，方便前后端联调的一款工具。

### 1、创建SpringBoot项目 ###

### 2、引入Swagger2的相关依赖 ###

<dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>2.9.2</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>2.9.2</version>
            </dependency>

我这里只是列出的Swagger2的依赖，并没有列出其他依赖，其他依赖根据自己的需求添加

### 3、开启Swagger2 ###

添加一个类SwaggerConfig专门配置Swagger，我们需要自定义Swagger的相关配置，但是这里我们先开启测试一下

@Configuration
    @EnableSwagger2
    public class SwaggerConfig { 
    }

记得加上`@Configuration`注解表示这是一个Spring的配置文件，`@EnableSwagger2`注解表示开启Swagger2

去浏览器测试一下，输入`http://localhost:8080/swagger-ui.html`

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NTc0NzA4MA_size_16_color_FFFFFF_t_70]

有了，说明我们开启成功，下面我们开始自定义相关配置

### 4、配置Swagger2 ###

@Configuration
    @EnableSwagger2
    public class SwaggerConfig { 
        @Bean
        public Docket docket(@Qualifier("apiInfo") ApiInfo apiInfo){ 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo);
        }
        //配置自定义作者信息apiInfo
        @Bean(name = "apiInfo")
        public ApiInfo apiInfo(){ 
            return new ApiInfo(
                    "wqk的swaggerAPI配置文档",
                    "Api接口配置文档",
                    "v1.0",
                    "urn:tos",
                    new Contact("wqk", "", "xxxxxxxx@gmail.com"),
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0",
                    new ArrayList()
            );
        }
    }

我们先创建一个ApiInfo方法，返回一个ApiInfo对象，如果你不想自定义一些作者信息的话就不需要new一个，就直接用默认的就行了。然后用Spring的方法把他返回给Doccket方法，就会出现如下效果：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NTc0NzA4MA_size_16_color_FFFFFF_t_70 1]  
这里的作者的可定制化程度还是挺高的，可以自己尝试一下配置

然后加下来就是在docket方法里面自定义扫描包或者其他的

@Configuration
    @EnableSwagger2
    public class SwaggerConfig { 
        @Bean
        public Docket docket(@Qualifier("apiInfo") ApiInfo apiInfo){ 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo)
                    //开启Swagger，默认是false
                    .enable(true)
                    .select()// 通过.select()方法，去配置扫描接口,RequestHandlerSelectors配置如何扫描接口
                    //扫描所有接口
                    //.apis(RequestHandlerSelectors.any())
                    //不扫描任何接口
                    //.apis(RequestHandlerSelectors.none())
                    //扫描控制器类方法上带有GetMapping注解的接口
                    //.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
                    //扫描控制器类上带有RequestMapping注解的接口
                    //.apis(RequestHandlerSelectors.withClassAnnotation(RequestMapping.class))
                    //扫描这个包里的接口
                    .apis(RequestHandlerSelectors.basePackage("cn.wqk.swagger.controller"))
                    //扫描这个请求路径的接口
                    //.paths(PathSelectors.ant("/wqk/**"))
                    .build();
        }
        //配置自定义作者信息apiInfo
        @Bean(name = "apiInfo")
        public ApiInfo apiInfo(){ 
            return new ApiInfo(
                    "wqk的swaggerAPI配置文档",
                    "Api接口配置文档",
                    "v1.0",
                    "urn:tos",
                    new Contact("wqk", "", "a954278478@gmail.com"),
                    "Apache 2.0",
                    "http://www.apache.org/licenses/LICENSE-2.0",
                    new ArrayList()
            );
        }
    }

其中还有一些给控制器或者实体类加上注释的Api注解

<table> 
 <thead> 
  <tr> 
   <th>注解</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>

@Api(tags = "Hello控制器")
    @RestController
    public class HelloController { 
        @ApiOperation("hello接口")
        @GetMapping("/hello")
        public String hello(){ 
            return "HelloSwagger!";
        }
    }

比如我给HelloController类加上`@Api(tags = "Hello控制器")`注解，给hello方法加上`@ApiOperation("hello接口")`注解，看看效果：

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NTc0NzA4MA_size_16_color_FFFFFF_t_70 2]

可以看到控制器和控制器里的方法都有了注释，这样前后端联调就会更加方便，其他注解你可以自行测试。

最后想特别谢谢一位up，狂神老师：https://space.bilibili.com/95256449?from=search&seid=15091236066275360244 讲的特别好，他的Mybatis，Spring，SpringMVC，SpringBoot个人感觉都讲得特别好，这篇就是他那节课的笔记。

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NTc0NzA4MA_size_16_color_FFFFFF_t_70]: /images/20210813/6db5eb5b83a74427b13212007c3a8eb4.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NTc0NzA4MA_size_16_color_FFFFFF_t_70 1]: /images/20210813/eee982a8b119405e9649cbcf0164d8c6.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80NTc0NzA4MA_size_16_color_FFFFFF_t_70 2]: /images/20210813/625b81d1b625454f84dae4a8484e43f0.png