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

news2024/11/24 5:44:16

一、场景

环境：

二、问题

思路：

三、解决方案（推荐）

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;


    @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;
    }
}