SpringBoot集成Swagger
Swagger主要作用就是为开发生成接口文档,方便前后端进行数据交互。通过更新Swagger的描述文件就能自动生成接口文档。
使用swagger可以直接通过代码生成接口文档,不再需要手动编写
并且提供了在线测试接口的api,参数与格式都是已经定义好的,直接在界面上传入对应的参数即可测试
swagger在与SpringBoot集成时会出现诸多问题,大概率是两者之间的版本冲突问题
我这里使用的是springBoot2.7.8,Swagger2.9.2
<!-- swagger2 -->
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
如果出现了错误可以尝试在SpringBoot的yaml文件中配置:spring.mvc.pathmatch.matching-strategy=ant_path_matcher
配置Swagger
对Swagger进行配置,使用配置类@Configuration
@Configuration
@EnableSwagger2 // 开启Swagger2
public class SwaggerConfig {
// 配置swagger的Bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
;
}
// 配置swagger apiInfo信息
public ApiInfo apiInfo(){
// 配置swagger界面展示信息 覆盖swagger的默认信息
Contact contact = new Contact("JaThink","blog.csdn.net/yuqu1028","yuqu1028@163.com");
return new ApiInfo("JaThink Interface Swagger",
"这山高",
"1.0",
"blog.csdn.net/yuqu1028",
contact,
"Apache 2.0",
"http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList());
}
}
Swagger配置扫描接口
继续使用Docket的select和build方法来配置,如下:
// 配置swagger的Bean实例
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 是否开启swagger
.enable(false)
.select()
// basePackage 指定扫描包
// any 扫描全部 none 全部不扫描
// withClassAnnotation:扫描类上的注解
// withMethodAnnotation:扫描方法上的注解
.apis(RequestHandlerSelectors.withMethodAnnotation(GetMapping.class))
// 只扫描yuqu请求下的
.paths(PathSelectors.ant("/yuqu/**"))
.build()
;
}
设置显示swagger的环境,项目测试维护时开启swagger,项目上线时关闭swagger
可以采用SpringBoot的多环境配置,使用spring.profiles.active来指定使用哪一个yaml配置文件( 即运行环境 )
在Docket中去配置
@Bean
public Docket docket(Environment environment){
// 配置使用swagger的环境
Profiles profiles = Profiles.of("dev");
// 获取项目环境
boolean flag = environment.acceptsProfiles(profiles);
// 如果当前环境为dev 那么就为true使用swagger 如果为false就考虑项目上线情况 不适用swagger
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
// 是否开启swagger
.enable(flag)
配置API多文档分组
调用Docket对象的groupName方法入参文档名,每个分组都有自己对应的配置信息
@Bean
public Docket docket2(){
return new Docket(DocumentationType.SWAGGER_2).groupName("第二组");
}
@Bean
public Docket docket3(){
return new Docket(DocumentationType.SWAGGER_2).groupName("第三组");
}
@Bean
public Docket docket4(){
return new Docket(DocumentationType.SWAGGER_2).groupName("第四组");
}
swagger2常用注解
@Api:用于类上的注解,控制整个类生成接口信息的内容。参数 tags:类名称,数组形式,可以有多个值。表示多个controllertest
@Api(tags = {"tags111","tags222"})
@ApiOperation:方法上注解,描述方法的相关信息。参数:value:方法描述、notes:方法笔记( 详细描述 )
@ApiOperation(value = "方法value",notes = "更多更多的描述")
@ApiParam:用于方法参数的注解,描述该参数。name:参数名称、value:参数作用、required:表示是否为必须参数,默认为false
public String test3(@ApiParam(name = "用户id",value = "用于查询当前用户") Integer id){