【日常总结】Swagger 3.0 + 集成 knife4j ,并设置header入参
上一节: 【日常总结】优雅升级Swagger 2 升至 3.0, 全局设置 content-type application/json-CSDN博客
一、场景
-
公司需要 集成 knife4j 方便调试 (带参数说明,请求参数缓存,全局入参如添加header入参)
-
思路 :集成 knife4j ,并开启请求参数缓存
环境:
-
Spring boot : 2.5.4
-
Swagger ui : 3.0
-
JDK : 1.8
二、问题
集成knife4j 后默认不带header入参,无法添加token参数,需要在每个接口添加如下代码,如
何全局添加参数呢
@RequestHeader(value = "token", required = false) String token
如:
思路 :
swagger 配置文件中添加全局参数
三、解决方案 (推荐)
Stage 1:接入knife4j 依赖
<!--knife4j-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
Stage 2:修改 yaml 配置
knife4j:
# 开启增强配置
enable: true
# 开启生产环境屏蔽
production: false
Stage 3:修改 swagger 3 配置文件
- 这里是header中添加默认 token
- 注意:这里的默认值不生效,我也不清楚为什么,有知道的小伙伴可以评论区留言
package com.whxph.xphservice.config;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import springfox.documentation.builders.*;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import java.util.ArrayList;
import java.util.List;
// 自定义swagger3文档信息
@Configuration
@ConditionalOnProperty(value = "springfox.documentation.enabled", havingValue = "true", matchIfMissing = true)
@Slf4j
public class Swagger3Config{
@Value(value = "${host:localhost}")
private String host;
@Value("${server.port:8005}")
private String port;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.paths(PathSelectors.any())
.build()
.globalRequestParameters(getGlobalRequestParameters())
.globalResponses(HttpMethod.GET, getGlobalResonseMessage())
.globalResponses(HttpMethod.POST, getGlobalResonseMessage());
}
private ApiInfo apiInfo() {
log.info("http://{}:{}/swagger-ui.html", host, port);
log.info("http://localhost:{}/swagger-ui.html", port);
log.info("http://localhost:{}/swagger-ui/index.html", port);
log.info("http://localhost:{}/doc.html", port);
return new ApiInfoBuilder()
.title("XPH- iot 接口文档")
.description("更多请咨询")
.contact(new Contact("lijiong", "https://", "xxx@"))
.version("1.0.0")
.build();
}
//生成全局通用参数
private List<RequestParameter> getGlobalRequestParameters() {
List<RequestParameter> parameters = new ArrayList<>();
parameters.add(new RequestParameterBuilder()
.name("token")
.description("认证")
.in(ParameterType.HEADER)
.query(q -> q.model(m -> m.scalarModel(ScalarType.STRING))
.defaultValue("123"))
.required(false)
.build());
return parameters;
}
//生成通用响应信息
private List<Response> getGlobalResonseMessage() {
List<Response> responseList = new ArrayList<>();
responseList.add(new ResponseBuilder().code("404").description("找不到资源").build());
return responseList;
}
}
Stage 4:查看效果
-
Swagger UI 3.0
-
knife4j 3.0
四、其他方案(不推荐)
网上很多博主使用 knife4j 的 文档管理 > 个性化设置 > 开启请求参数缓存
会带来页面上有多余空格,如果有洁癖的客观,请使用修改 swagger 3 配置文件的解决方案