一、概述
在这篇博客中,会记录springfox3
的基本配置与使用;由于swagger-ui看得不是很习惯,额外引入了knife4j
,使用增强版本的swagger的前端ui。
二、依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-ui</artifactId>
<version>3.0.3</version>
</dependency>
三、swagger的配置和使用
1.在这里不使用注解@EnableOpenApi。
2.Swagger3Config.java进行配置
@Configuration
@ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true)
public class Swagger3Config {
@Bean
public Docket createRestApi() {
// 添加token参数
RequestParameterBuilder requestParameterBuilder = new RequestParameterBuilder()
.name("token")
.description("token")
.in(ParameterType.HEADER)
// 类内部创建了默认的builder以供属性设置
.query(parameterSpecificationBuilder -> parameterSpecificationBuilder.defaultValue("1")
.allowEmptyValue(true));
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.paths(PathSelectors.any())
.build()
.globalRequestParameters(Lists.newArrayList(requestParameterBuilder.build()));
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("xxxxxxxxxxxxxx")
// .description("springboot | swagger")
// .contact(new Contact("", "", ""))
// .version("1.0.0")
.build();
}
}
注意
@ConditionalOnProperty
注解声明了当springfox.documentation.enabled
为true
时启用配置,而且默认值就是true
(Swagger仅仅建议在开发阶段使用);
3.对一些内置接口的访问放行
这里以WebMvcConfig
为例。
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(loginInterceptor).addPathPatterns("/**")
.excludePathPatterns("/login")
.excludePathPatterns("/js/**")
.excludePathPatterns("/css/**")
.excludePathPatterns("/image/**")
.excludePathPatterns("/uploads/**")
// swagger
.excludePathPatterns("/swagger-ui.html", "/swagger-resources/**", "/webjars/**", "/v3/**", "/swagger-ui.html/**")
// knife4j
.excludePathPatterns("/doc.html", "/doc.html/**");
registry.addInterceptor(sqlInjectInterceptor).addPathPatterns("/**");
}
4.基本使用
Swagger2注解 | 简单说明 |
---|---|
@Api(tags = "xxx模块说明") | 作用在模块类上 |
@ApiOperation("xxx接口说明") | 作用在接口方法上 |
@ApiModel("xxxPOJO说明") | 作用在模型类上:如VO、BO |
@ApiModelProperty(value = "xxx属性说明",hidden = true) | 作用在类方法和属性上,hidden设置为true可以隐藏该属性 |
@ApiParam("xxx参数说明") | 作用在方法的参数上 |
@ApiImplicitParams | 用在请求的方法上,表示一组参数说明 |
@ApiImplicitParam
用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
四、登录页面查看接口文档
swagger页面:项目地址 + /swagger-ui/index.html
knife4j页面:项目地址 + /doc.html
五、遇到的问题
1. swagger3中,设置全局参数不生效
网友评论