SpringBoot集成Swagger

1. Swagger

Swagger是一个根据代码自动生成API文档的框架，用于生成可视化RESTful风格的Web服务接口文档。

在当下项目前后端分离情况下，接口文档对前后端开发发挥了重要的作用，而Swagger框架就可以将后端定义的接口信息生成对应的API文档，并可以进行接口的请求模拟。

Swagger官方网站

Swagger框架已经更新至V3.x版本，但是为了稳定和适用性，仍然引入使用较多的V2.X版本。

2. SpringBoot中引入Swagger

2.1 依赖信息

在SpringBoot项目中通过引入相关的依赖信息来集成Swagger框架，Swagger使用的maven依赖信息包括springfox-swagger2和springfox-swagger-ui两个依赖。

• springfox-swagger2作为Swagger2.X版本的核心依赖
• springfox-swagger-ui则是用来提供Swagger可视化接口文档页面

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

2.2 自定义Swagger配置

引入Swagger使用的依赖后，为了能在项目中开启Swagger功能，还需要对Swagger进行配置。

创建Swagger配置类，并添加@Configuration和@EnableSwagger2注解

• @Configuration注解标注该类作为SpringBoot配置类
• @EnableSwagger2注解表示开启Swagger功能

@EnableSwagger2
@Configuration
public class SwaggerConfig {
    ...
}

在配置类中还需要定义Swagger应用配置的bean对象。

//定义swagger应用配置对象，//设置根据类的注解@Api获取接口信息
@Bean
public Docket createRestApi(){
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo()) 
        .select()
        .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
        .paths(PathSelectors.any())
        .build();
}
​
//定义swagger-ui展示内容
private ApiInfo apiInfo(){
    return new ApiInfoBuilder()
        .title("Swagger接口文档")
        .description("Swagger生成的文档信息")
        .version("1.0")
        .build();
}

对于配置类中定义的createRestApi()方法，最终返回了Docket对象，并将该对象通过@Bean注解交给Spring容器进行管理。

• Docket类型就是Swagger-Documentation的类型，实现了DocumentationPlugin接口
• DocumentationType.SWAGGER_2作为初始化参数表示创建的是Swagger2.x版本对象
• apiInfo()方法接收一个ApiInfo参数设置接口文档信息，ApiInfo对象使用单独方法定义
  • title()设置接口文档标题信息
  • description()设置接口文档描述信息
  • version()则定义接口文档的版本
• select()方法则是为Docket对象增加一个ApiSelectorBuilder查询对象
• apis()方法是设置项目中接口信息的获取方式，RequestHandlerSelectors中有多种方式
  • withClassAnnotation()，根据类注解获取
  • withMethodAnnotation()，根据方法注解获取
  • basePackage()，根据包路径获取
• paths()方法用于配置项目中接口在在swagger-ui上暴露规则
  • 全部暴露
  • 全部隐藏
  • 根据自定义正则表达式选择公开
• 最后使用build()方法创建一个正在的Docket对象

2.3 访问Swagger-ui

引入依赖，设置Swagger的配置信息后，可以通过http://localhost:8080/swagger-ui.html访问Swagger-Ui界面。

3. 使用Swagger

3.1 定义swagger接口

如果想要一个web服务的接口信息加入到Swagger-ui中，我们在配置Swagger时使用了apis(RequestHandlerSelectors.withClassAnnotation(Api.class))方法，其中参数代表根据类上使用的@APi注解来将当前类中的接口方法加入到Swagger-ui中。

除了以上方式之外，还可以使用withMethodAnnotation()方法并传入一个方法注解来将接口加入Swagger-ui；以及使用basePackage()方法，传入路径，则当前路径下的所有服务方法加入到Swagger-ui中。

//使用@Api定义，类中的接口信息暴露在swaager-ui中
@Api
@RestController
public class FileUploadController {
    ...
}

打开接口信息页面可以看到

3.2 Swagger框架的常用注解

• @Api，注解标注在类上，表示当前类加入到Swagger-ui中，并可以设置显示名称等属性
• @ApiIngore，标注在类上，表示当前类不加入到swagger-ui中
• @ApiOperation，标注在方法上，可以定义当前方法在swagger-ui中展示信息
• @ApiParam，用于参数，对接口方法传参进行自定义
• @APiModel和@ApiModelProperty，标注模型类和类中属性，用于描述信息
• @ApiResponse和@APiResponses，用于接口方法上，用来描述接口返回结果参数信息
• @ApiError，标注在方法上，用来描述方法错误时返回的信息