【日常总结】Swagger 3.0 + 集成 knife4j ，并设置header入参

一、场景

环境：

二、问题

思路：

三、解决方案（推荐）

Stage 1：接入knife4j 依赖

Stage 2：修改 yaml 配置

Stage 3：修改 swagger 3 配置文件

Stage 4：查看效果

Swagger UI 3.0

knife4j 3.0

四、其他方案（不推荐）

上一节: 【日常总结】优雅升级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;@Beanpublic 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;}
}