关于SpringBoot+Swagger3.0

关于吐槽

  本来我是很不喜欢Swagger这种侵入式的工具的，但是我更不喜欢去写接口文档。这里记录一下我对于Swagger3.0的配置和使用。

关于版本

1. Spring Boot 2.5.6
2. Swagger 3.0

关于配置

1. 添加依赖

在pom.xml文件添加如下的依赖(knife4j 是无关紧要的)

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

2. 添加配置类

创建了一个新的配置文件(SwaggerConfig)

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.ResponseBuilder;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

@Configuration
@EnableOpenApi
public class SwaggerConfig {

	@Bean
	public Docket desertsApi() {
		return new Docket(DocumentationType.OAS_30)
				// 创建该API的基本信息，自定义的展示信息
				.apiInfo(apiInfo())
				// 设置那些接口暴露给Swagger
				.select()
				// 扫描所有的 ApiOperation 标签的方法
				.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
				// 扫描所有具有 Api 标签的类
				//.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
				// 扫描该文件夹下所有的接口
				//.apis(RequestHandlerSelectors.basePackage("com.fanju.media.controller"))
				.paths(PathSelectors.any())
				.build();
	}

	/**
	 * 构建API文档的详细信息函数
	 * 注意这里的注解引用的是哪个
	 *
	 * @return
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("xxxxAPI接口文档")
				.description("API接口文档")
				.contact(new Contact("xxx", "", "xxx@qq.com"))
				.version("1.0")
				.build();
	}
}

这里 apis 需要注意一下：

• RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class) 是指扫描所有配置了 @ApiOperation 注解的方法
• RequestHandlerSelectors.withClassAnnotation(Api.class) 是指扫描所有配置了 @Api 注解的类
• RequestHandlerSelectors.basePackage(“pers.ysy.controller”) 是指扫描该路径下的所有Controller

3. 拦截器

拦截器会拦截掉Swagger的一些文件，所以需要设置一下。这里的拦截器实现了 WebMvcConfigurer 接口，然后添加如下代码

@Override
	public void addResourceHandlers(ResourceHandlerRegistry registry) {
		
		registry.addResourceHandler("/swagger-ui/**").addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
		registry.addResourceHandler("favicon.ico").addResourceLocations("classpath:/static/favicon.ico");
		registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
	}

4. 配置文件

在 application.yml 文件中配置一下，可以控制Swagger的开启关闭

# 是否开启Swagger
springfox:
  documentation:
    enabled: true

关于使用

1. Controller

• 在类上添加 @Api 注解
• 在方法上添加 @ApiOperation 注解

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/test/")
@Api(tags = "测试")
public class TestController {
	
	@PostMapping("world")
	@ApiOperation("helloworld")
	public String getWorld() {
		return "Hello World";
	}
	
}

2. POJO类

• 在类上添加 @ApiModel 注解
• 在变量上添加 @ApiModelProperty 注解

@ApiModel("通用返回对象")
public class ResponseResult implements Serializable {

	@ApiModelProperty(hidden = true)
	private static final long serialVersionUID = 40117602649286465L;

	@ApiModelProperty(value = "返回编码", example = "200")
	private Integer code;

	@ApiModelProperty(value = "返回信息", example = "操作成功")
	private String msg;

	@ApiModelProperty(value = "返回数据")
	private Object data;

}

关于测试

启动项目 访问 http://localhost:8080/swagger-ui/#/