SpringBoot集成Swagger2

---

前言

本文实现了SpringBoot集成Swagger2，并优化UI界面及一些常用注解的介绍。

---

一、引入依赖

在pom文件中引入如下依赖：

 <!--Swagger2依赖-->
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.9.2</version>
 </dependency>
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger-ui</artifactId>
     <version>2.9.2</version>
 </dependency>

 <!--swagger UI美化-->
 <dependency>
     <groupId>com.github.xiaoymin</groupId>
     <artifactId>swagger-bootstrap-ui</artifactId>
     <version>1.9.3</version>
 </dependency>

二、配置与案例

1、配置文件

代码如下：

@Configuration
@EnableSwagger2 //开启Swagger
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//扫描类上有@Api注解的类
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(setHeaderToken());

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("测试Swagger文档")//swagger文档的浏览器标题，类似于html里的title
                .description("Swagger实例")//文档主页【简介】栏参数
                .termsOfServiceUrl("127.0.0.1:8088")//文档主页【服务Url】栏参数
                .version("2.0")//文档主页【版本】栏参数
                .build();
    }

    /**
     * @Description: 设置swagger文档中全局参数  请求接口时可传可不传
     * @return: java.util.List<springfox.documentation.service.Parameter>
     */
    private List<Parameter> setHeaderToken() {
        List<Parameter> pars = new ArrayList<>();
        ParameterBuilder parameterBuilder = new ParameterBuilder();
        parameterBuilder
                .name("token")//参数名称
                .description("用户TOKEN")//参数介绍
                .modelRef(new  ModelRef("string"))//参数类型
                .parameterType("header")//请求类型
                .required(false).build();//是否必传
        pars.add(parameterBuilder.build());

        ParameterBuilder parameterBuilder1 = new ParameterBuilder();
        parameterBuilder1
                .name("test")
                .description("测试全局参数")
                .modelRef(new  ModelRef("string"))
                .parameterType("header")
                .required(true).build();
        pars.add(parameterBuilder1.build());
        return pars;
    }
}

2、接口案例

编写一个Controller测试

@RestController
@RequestMapping("/test")
@Api(tags = {"Swagger测试Controller"})
public class SwaggerController {


    @ApiOperation(value = "测试接口",notes = "接口描述")
    @PostMapping
    public ResponseEntity<String> test(@RequestBody TUser tUser){
        System.out.println(tUser);
        return ResponseEntity.ok("SUCCESS");
    }
}

3、效果

请求地址为：IP:端口/doc.html
效果图如下：

三、注解

1、@Api

@Api： 作用在类上，标识该类为一个接口组

参数	作用
tags	描述该类，在文档上会已该参数命名显示。

【实例】：

【效果】：

2、@ApiOperation

@ApiOperation：作用在被【@Api】标记类下的方法上，标识该方法，并在文档上显示在对应的接口组下

参数	作用
value	接口命名，在文档上会已该参数命名显示。
notes	描述该接口，在文档上会已该参数命名显示。

【实例】：

【效果】：

3、@ApiModelProperty

@ApiModelProperty：作用属性参数上，描述该属性。

参数	作用
value	描述该属性。
required	是否必传，默认为false。该参数只支持form-data类型请求，不支持json格式。

【实例】：

【form-data效果】：

【json效果】：

4.@ApiImplicitParam和@ApiImplicitParams

参数	作用
paramType	请求类型
dataType	数据类型
name	参数名字
value	参数说明

@ApiImplicitParam： 单字段标记，作用与单独得请求参数上，该注解需要写在方法上`

【实例图】：

【实际效果】:

@ApiImplicitParams： 多个单字段标记，作用与多个单独得请求参数上，该注解需要写在方法上。
【实例图】：

【实际效果】:

---

总结

本文主要记录如何在SpringBoot中集成Swagger2文档，并介绍了一些常用注解及注解的常用参数。