springboot2.6.3整合knife4j 3.0.3

背景

最近由于项目使用的swaggerui存在查找接口不方便，ui不美观等问题，决定使用基于swagger的knife4j替换swagger ui，从swagger ui升级到knife4j极其简单，官方效果如下：
https://doc.xiaominfo.com/demo/doc.html

目标

搭建knife4j在线接口文档，并且支持在线调试，下载接口文档到本地，直在dev环境引入knife4j依赖，其余环境不引入。

过程

1. 通过maven profile特性在dev环境引入knife4j依赖

<profiles>
        <profile>
            <id>dev</id>
            <properties>
                <!-- 环境标识，需要与配置文件的名称相对应 -->
                <profiles.active>dev</profiles.active>
                <revision>1.0.0-SNAPSHOT</revision>
            </properties>
            <dependencies>
                <!--               dev才加入在线文档依赖 -->
                <dependency>
                    <groupId>com.github.xiaoymin</groupId>
                    <artifactId>knife4j-spring-boot-starter</artifactId>
                    <version>3.0.3</version>
                </dependency>
            </dependencies>
        </profile>
    </profiles>

maven打包需指定profile，如mvn clean package -Pdev -Dmaven.test.skip=true
2. dev 配置文件配置

spring:
# swagger问题修复
    mvc:
        pathmatch:
            matching-strategy: ant_path_matcher
# Swagger配置
swagger:
    # 是否开启swagger
    enabled: true
    # 请求前缀
    pathMapping: /dev-api
knife4j:
    enable: true
    setting:
        enableDebug: true

3. idea指定profile为dev
   
4. 配置knife4j支持经由网关访问并且调试，网关地址映射/dev-api => /admin
   • 配置前：
     

• 配置代码

@Configuration
@ConditionalOnProperty(name = "swagger.enabled", havingValue = "true")
public class SwaggerConfig
{
    @Value("${server.servlet.context-path:}")
    private String contextPath;

    @Bean
    public Docket defaultApi(Environment evn) {
    	//接口地址前缀，如/api
        String pathMapping = evn.getProperty("swagger.pathMapping");

        Docket docket = new Docket(DocumentationType.OAS_30)
            .enable(true)
            .apiInfo(new ApiInfoBuilder()
                .title("在线swagger接口文档")
                .contact(new Contact("xxx", "", ""))
                .description("前端对接使用")
                .build())
            .select()
            //只收集带有swagger注解的
            .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            //指定Controller扫描包路径
            .apis(RequestHandlerSelectors.basePackage("com.xx.xx.controller"))
            .paths(PathSelectors.any())
            .build()
            /* 设置安全模式，swagger可以设置访问token */
            .securitySchemes(securitySchemes())
            .securityContexts(securityContexts())
            .pathMapping(pathMapping)
            //用了网关地址重写，需要去除server.servlet.context-path设置的地址前缀，换成网关的/dev-api前缀
            .pathProvider(new CustomerPathProvider());

        return docket;
    }
    /**
     * 安全模式，这里指定token通过Authorization头请求头传递
     */
    private List<SecurityScheme> securitySchemes()
    {
        return List.of(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
    }

    /** 用了网关，去除server.servlet.context-path 地址前缀，使用pathMapping */
    private class CustomerPathProvider extends DefaultPathProvider {

        @Override
        public String getOperationPath(String operationPath) {
            String path = super.getOperationPath(operationPath);
            return path.replace(contextPath, "");
        }
    }
    
    /**
     * 安全上下文
     */
    private List<SecurityContext> securityContexts()
    {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(
                SecurityContext.builder()
                        .securityReferences(defaultAuth())
                        .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
                        .build());
        return securityContexts;
    }

    /**
     * 默认的安全上引用
     */
    private List<SecurityReference> defaultAuth()
    {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }
    /**
     * 解决Spring Boot 2.6.x 与Swagger 3.0.0 不兼容问题
     **/
    @Bean
    public WebMvcEndpointHandlerMapping webEndpointServletHandlerMapping(WebEndpointsSupplier webEndpointsSupplier, ServletEndpointsSupplier servletEndpointsSupplier, ControllerEndpointsSupplier controllerEndpointsSupplier, EndpointMediaTypes endpointMediaTypes, CorsEndpointProperties corsProperties, WebEndpointProperties webEndpointProperties, Environment environment) {
        List<ExposableEndpoint<?>> allEndpoints = new ArrayList();
        Collection<ExposableWebEndpoint> webEndpoints = webEndpointsSupplier.getEndpoints();
        allEndpoints.addAll(webEndpoints);
        allEndpoints.addAll(servletEndpointsSupplier.getEndpoints());
        allEndpoints.addAll(controllerEndpointsSupplier.getEndpoints());
        String basePath = webEndpointProperties.getBasePath();
        EndpointMapping endpointMapping = new EndpointMapping(basePath);
        boolean shouldRegisterLinksMapping = this.shouldRegisterLinksMapping(webEndpointProperties, environment, basePath);
        return new WebMvcEndpointHandlerMapping(endpointMapping, webEndpoints, endpointMediaTypes, corsProperties.toCorsConfiguration(), new EndpointLinksResolver(allEndpoints, basePath), shouldRegisterLinksMapping, null);
    }
    private boolean shouldRegisterLinksMapping(WebEndpointProperties webEndpointProperties, Environment environment, String basePath) {
        return webEndpointProperties.getDiscovery().isEnabled() && (StringUtils.hasText(basePath) || ManagementPortType.get(environment).equals(ManagementPortType.DIFFERENT));
    }
}

• 配置后：