SpringBoot整合swagger2

Spring Boot版本:2.4.5

1.引入依赖

<!--swaggerApi-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!--swagger官方ui-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. Swagger 配置

@Configuration
@EnableSwagger2
//WebMvcConfigurationSupport 配置swagger2的静态资源路径
//正式环境关闭swagger
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class SwaggerConfig {
    
	@Value("${swagger.enable}")
	private boolean enableSwagger;
    
	/**
	 * @description:  创建api文档的详细信息函数
	 * @params:
	 * @return:
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				//页面标题
				.title("zzyNotes")
				//描述
				.description("zzyNotes 这里是描述")
            	//声明
				.termsOfServiceUrl("声明:仅作为学习使用")
            	//联系方式
				.contact(new Contact("zzy", "www.baidu.com", "zzy530783806@163.com"))
            	//版本号
				.version("1.0")
				.build();
	}
	/**
	 * @description:  创建Docket,可创建多组
	 * @params:
	 * @return:
	 */
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
                //api信息
	            .apiInfo(apiInfo())
            	//分组名
				.groupName("我是swagger")
            	//是否展示该Docket,默认为true
				.enable(true)
				.select()
            	//*扫描策略(扫描哪些接口)
            	//全部
				.apis(RequestHandlerSelectors.any())
            	//类上有@APi
				.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
            	//方法上有@ApiOperation
				.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            	//包路径
				.apis(RequestHandlerSelectors.basePackage("com.zzy.zzyNotes.controller.study"))
            	//多包
            	.apis(Predicates.or(
                        RequestHandlerSelectors.basePackage("com.ftsino.citychallenge.api.controller.arScenic"),
                        RequestHandlerSelectors.basePackage("com.ftsino.citychallenge.api.controller.scenic")
                ))
            	//*路径匹配策略(留下哪些接口)
            	//全部匹配
	            .paths(PathSelectors.any())
            	//全部不匹配
	            .paths(PathSelectors.none())
            	//URL匹配 ant 模式
				.paths(PathSelectors.ant("/**"))
            	//没有分文件夹的,按Mapping路径(不带context-path路径)分组
                .paths(Predicates.or(
                        PathSelectors.ant("/newSysBoxActivities/**"),
                        PathSelectors.ant("/newSysBoxInfo/**")))
            	//正则匹配路径
				.paths(PathSelectors.regex("正则表达式"))
				.build()
				.globalOperationParameters(globalOperation());
	}
    
	/**
	 * @description: 添加参数
	 * @params:
	 * @return: 
	 */
	private List<Parameter> globalOperation(){
		//添加head参数配置start
		ParameterBuilder tokenPar = new ParameterBuilder();
		List<Parameter> pars = new ArrayList<>();
		//第一个token为传参的key，第二个token为swagger页面显示的值
		tokenPar.name("token").description("token").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
		pars.add(tokenPar.build());
		return pars;
	}
}

3.正式环境不展示

@Value("${swagger.enable}")
	private boolean enableSwagger;

方法1: 创建 Docket 时的.enable()

@Bean
public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .groupName("我是swagger")
        //这里控制Docket是否展示
        .enable(enableSwagger)
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build()
        .globalOperationParameters(globalOperation());
}

注意!:enable(false)时swagger也会加载,只是这个docket不展示

方法2: 类上加@ConditionalOnProperty(name = “swagger.enable”, havingValue = “true”) 建议使用

@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class SwaggerConfig {
	//...
}

注意!:关键是@ConditionalOnPropert,它有两个参数,name和havingValue
name加载配置文件,如果这个值和havingValue的值相同,则spring将加载这个Bean,反之不加载

4.常用注解

1.@Api()

--加在controller上
--参数
tags:列表controller名字

2.@ApiOperation()

--加在接口方法上
--参数
value=“方法的用途和作用”
notes=“方法的注意事项和备注”
tags：说明该方法的作用，参数是个数组，可以填多个。
格式：tags={“作用1”,“作用2”}
（在这里建议不使用这个参数，会使界面看上去有点乱，前两个常用）
response:返回类.class

3.@ApiModel()

--加载实体类上
--参数
value=“名字”
description=“描述实体的作用”

4.@ApiModelProperty()

--用在实体字段上
--参数
value=“用户名” 描述参数的意义
name=“name” 参数的变量名
required=true 参数是否必选

5.@ApiImplicitParams

-- 用在接口方法上
--参数
@ApiImplicitParam

6.@ApiImplicitParam

-- 用在接口方法上
-- 
name=“参数ming”
value=“参数说明”
dataType=“数据类型”
paramType=“query” 表示参数放在哪里
-header–>请求参数的获取：@RequestHeader(代码中接收注解)
 -query–>请求参数的获取：@RequestParam(代码中接收注解)
 -path（用于restful接口）–>请求参数的获取：@PathVariable(代码中接收注解)
 -body–>请求参数的获取：@RequestBody(代码中接收注解)
 -form（不常用，form.serilize()）
defaultValue=“参数的默认值”
required=“true” 表示参数是否必须传

7.@ApiResponses()

-- 用在接口方法上
--参数
@ApiResponse

8.@ApiResponse()

-- 用在接口方法上
--参数
code = 返回码
message = 对应消息