【日常总结】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 依赖

        
        
            com.github.xiaoymin
            knife4j-spring-boot-starter
            3.0.3
        

 

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 getGlobalRequestParameters() {
        List 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 getGlobalResonseMessage() {
        List 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 配置文件的解决方案