springcloud-gateway集成knife4j(swagger3)

springcloud-gateway集成knife4j(swagger3)

  • springcloud-gateway集成knife4j(swagger3)
    • 环境信息
    • 准备工作
    • 微服务集成knife4j
      • 第一步:编写Knife4jApiInfoProperties
      • 第二步:编写配置类Knife4jConfig
      • 第三步:放行相关资源 & 保证启动了knife4j
    • 网关集成knife4j
      • 编写配置类Knife4jGatewayConfig
    • 测试验证
    • 相关资料

环境信息

  • spring-boot:2.6.13
  • spring-cloud-alibaba:2021.0.5.0
  • knife4j-spring-boot-starter:3.0.3

准备工作

各微服务&网关引入依赖

<dependency>
    <groupId>com.github.xiaoymingroupId>
    <artifactId>knife4j-spring-boot-starterartifactId>
    <version>3.0.3version>
dependency>

微服务集成knife4j

第一步:编写Knife4jApiInfoProperties

import com.ideaaedi.springcloud.jd.commonspring.config.Knife4jConfig;
import lombok.Data;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

/**
 * api 基础信息配置。更多配置信息项见{@link Knife4jConfig}
 *
 * @author JustryDeng 
 * @since 2021.0.1.D
 */
@Data
@Component
public class Knife4jApiInfoProperties {
    
    /**
     * 要扫描api的base包
     */
    @Value("${api-info.base-package:com}")
    private String basePackage;
    
    /**
     * 是否启用登录认证
     */
    @Value("${api-info.enable-security:true}")
    private boolean enableSecurity;
    
    /**
     * 文档标题
     */
    @Value("${api-info.title:}")
    private String title;
    
    /**
     * 文档描述
     */
    @Value("${api-info.description:api info}")
    private String description;
    
    /**
     * 文档版本
     */
    @Value("${api-info.version:1.0.0}")
    private String version;
    
    /**
     * 联系人姓名
     */
    @Value("${api-info.contact-name:JustryDeng}")
    private String contactName;
    
    /**
     * 联系人网址
     */
    @Value("${api-info.contact-url:https://gitee.com/JustryDeng/projects}")
    private String contactUrl;
    
    /**
     * 联系人邮箱
     */
    @Value("${api-info.contact-email:[email protected]}")
    private String contactEmail;
}

第二步:编写配置类Knife4jConfig

import com.fasterxml.jackson.databind.introspect.BeanPropertyDefinition;
import com.github.xiaoymin.knife4j.core.model.MarkdownProperty;
import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import com.ideaaedi.springcloud.jd.commonds.constant.BaseConstant;
import com.ideaaedi.springcloud.jd.commonds.support.EnumDescriptor;
import io.swagger.annotations.ApiModelProperty;
import io.swagger.annotations.ApiParam;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.reflect.FieldUtils;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.lang.NonNull;
import org.springframework.lang.Nullable;
import org.springframework.stereotype.Component;
import org.springframework.stereotype.Controller;
import org.springframework.util.CollectionUtils;
import org.springframework.util.ReflectionUtils;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ModelSpecificationBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.PropertySpecificationBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.builders.RequestParameterBuilder;
import springfox.documentation.schema.ScalarType;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.Contact;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.schema.ModelPropertyBuilderPlugin;
import springfox.documentation.spi.schema.contexts.ModelPropertyContext;
import springfox.documentation.spi.service.ParameterBuilderPlugin;
import springfox.documentation.spi.service.contexts.ParameterContext;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import javax.annotation.Resource;
import java.lang.reflect.Field;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import java.util.Objects;
import java.util.Optional;
import java.util.stream.Collectors;

/**
 * Knife4j配置
 *
 * @author JustryDeng 
 * @since 1.0.0
 */
@Slf4j
@Configuration
@EnableSwagger2
public class Knife4jConfig implements WebMvcConfigurer {
    
    /** 对于管控了权限的应用,应放行以下资源 */
    public static String[] RESOURCE_URLS = new String[]{"/webjars/**", "/swagger**", "/v3/api-docs", "/doc.html"};
    
    @Value("${spring.application.name:default}")
    private String applicationName;
    
    @Resource
    private OpenApiExtensionResolver openApiExtensionResolver;
    
    @Bean
    public Docket docket() {
        // 指定使用Swagger2规范
        Docket docket = new Docket(DocumentationType.OAS_30)
                .apiInfo(new ApiInfoBuilder()
                        // 简介(支持Markdown语法)
                        .description("# 我是API简介")
                        // 服务地址
                        .termsOfServiceUrl("http://local.idea-aedi.com/")
                        // 作者及联系信息
                        .contact(new Contact("JustryDeng", "https://gitee.com/JustryDeng", "[email protected]"))
                        // api版本
                        .version("1.0.0")
                        .build())
                //分组名称(微服务项目可以用微服务名分组)
                .groupName(applicationName)
                .select()
                // 定位api
                .apis(
                        RequestHandlerSelectors.basePackage(getProjectBasePackage())
                                .and(RequestHandlerSelectors.withClassAnnotation(RestController.class)
                                        .or(RequestHandlerSelectors.withClassAnnotation(Controller.class))
                                )
                )
                .paths(PathSelectors.any())
                .build();
        
        docket.securitySchemes(securitySchemes()).securityContexts(securityContexts());
        
        // 自定义文档解析
        try {
            Field markdownPropertiesField = FieldUtils.getDeclaredField(OpenApiExtensionResolver.class,
                    "markdownProperties", true);
            List<MarkdownProperty> markdownProperties = (List<MarkdownProperty>)markdownPropertiesField.get(openApiExtensionResolver);
            if (!CollectionUtils.isEmpty(markdownProperties)) {
                for (MarkdownProperty markdownProperty : markdownProperties) {
                    docket.extensions(openApiExtensionResolver.buildExtensions(markdownProperty.getGroup()));
                }
            }
        } catch (IllegalAccessException e) {
            throw new RuntimeException(e);
        }
        
        return docket;
    }
    
    private List<SecurityScheme> securitySchemes() {
        // 设置请求头信息
        List<SecurityScheme> result = new ArrayList<>();
        // 第一个参数name,自定义即可。 在配置securityContexts时,通过此name对应到apiKey即可
        // 第二个参数,header name自定义即可。 如:JWT_TOKEN_KEY=Auth-Token,然后在代码里request.getHeader(JWT_TOKEN_KEY)取值
        /// swagger 2
        /// ApiKey apiKey = new ApiKey("auth-info", BaseConstant.JWT_TOKEN_KEY, "header");
        // swagger3这里应该是个bug:页面上(参数key、参数名)实际展示及生效的都是第一个参数. 所以这里都直接用BaseConstant.JWT_TOKEN_KEY
        ApiKey apiKey = new ApiKey(BaseConstant.JWT_TOKEN_KEY, BaseConstant.JWT_TOKEN_KEY, "header");
        result.add(apiKey);
        return result;
    }
    
    private List<SecurityContext> securityContexts() {
        // 设置需要登录认证的路径
        List<SecurityContext> result = new ArrayList<>();
        List<SecurityReference> securityReferences = defaultAuth();
        result.add(
                SecurityContext.builder().securityReferences(securityReferences).forPaths(
                        // 当直接使用swagger文档发送请求时,这些api需要满足securityReferences认证要求
                        PathSelectors.regex("/.*")
                                .and(
                                        // 当直接使用swagger文档发送请求时,这些api不需要满足securityReferences认证要求. '.*'表示匹配所有
                                        PathSelectors.regex("/hello.*").or(PathSelectors.regex("/hi.*"))
                                                .negate()
                                )
                ).build()
        );
        return result;
    }
    
    private List<SecurityReference> defaultAuth() {
        List<SecurityReference> result = new ArrayList<>();
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        // 这里指定使用哪个apiKey进行认证鉴权. 这里指定使用上面名为BaseConstant.JWT_TOKEN_KEY的apiKey
        result.add(new SecurityReference(BaseConstant.JWT_TOKEN_KEY, authorizationScopes));
        return result;
    }
    
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
    
    /**
     * 获取项目包前缀
     */
    private String getProjectBasePackage() {
        String projectBasePackage;
        String currPackageName = this.getClass().getPackage().getName();
        String[] packageItemArr = currPackageName.split("\\.");
        if (packageItemArr.length > 3) {
            projectBasePackage = String.join(".", packageItemArr[0], packageItemArr[1], packageItemArr[2]);
        } else {
            projectBasePackage = currPackageName;
        }
        log.info("Base package to scan api is -> {}", projectBasePackage);
        return projectBasePackage;
    }
    
    /**
     * 显示自定义枚举类型注释
     * 

*
参考here */ @Component @SuppressWarnings("unchecked") public static class Knife4jSwaggerEnumPlugin implements ModelPropertyBuilderPlugin, ParameterBuilderPlugin { private static final Field parameterDescriptionField; private static final Field modelPropertyBuilderDescriptionField; static { parameterDescriptionField = ReflectionUtils.findField(RequestParameterBuilder.class, "description"); Objects.requireNonNull(parameterDescriptionField, "parameterDescriptionField should noe be null."); ReflectionUtils.makeAccessible(parameterDescriptionField); modelPropertyBuilderDescriptionField = ReflectionUtils.findField(PropertySpecificationBuilder.class, "description"); Objects.requireNonNull(modelPropertyBuilderDescriptionField, "ModelPropertyBuilder_descriptionField should noe be null."); ReflectionUtils.makeAccessible(modelPropertyBuilderDescriptionField); } /** * {@link ApiModelProperty}相关 *

* 主要处理枚举对象直接作为方法参数的内部字段的情况. 如: *

         *     @Data
         *     public class LoginTokenRespVO {
         *   
         *         @ApiModelProperty("用户类型")
         *         private UserTypeEnum userType;
         *     }
         * 
*/
@Override public void apply(ModelPropertyContext context) { Optional<BeanPropertyDefinition> optional = context.getBeanPropertyDefinition(); if (!optional.isPresent()) { return; } // 对应被@ApiModelProperty标注的字段 BeanPropertyDefinition beanPropertyDefinition = optional.get(); Class<?> fieldType = beanPropertyDefinition.getField().getRawType(); if (!Enum.class.isAssignableFrom(fieldType)) { return; } Class<Enum<?>> enumType = (Class<Enum<?>>) fieldType; Enum<?>[] enumConstants = enumType.getEnumConstants(); PropertySpecificationBuilder modelPropertyBuilder = context.getSpecificationBuilder(); Object oldValue = ReflectionUtils.getField(modelPropertyBuilderDescriptionField, modelPropertyBuilder); // 解析枚举 List<String> enumDescList = Arrays.stream(enumConstants).map(this::obtainEnumDescription).collect(Collectors.toList()); modelPropertyBuilder.description((oldValue == null ? BaseConstant.EMPTY : oldValue) + buildHtmlUnOrderList(enumDescList)) .type(new ModelSpecificationBuilder().scalarModel(ScalarType.UUID).build()); } /** * {@link ApiParam}、{@link io.swagger.v3.oas.annotations.Parameter}相关. *

主要处理:枚举对象直接作为方法参数的情况. 如: *

         *     @PostMapping("/test1")
         *     @ApiOperation(value = "测试1")
         *     public void test1(@ApiParam(value = "用户类型", required = true) UserTypeEnum userTypeEnum)
         * 
*/
@Override public void apply(ParameterContext context) { Class<?> type = context.resolvedMethodParameter().getParameterType().getErasedType(); RequestParameterBuilder parameterBuilder = context.requestParameterBuilder(); if (!Enum.class.isAssignableFrom(type)) { return; } Class<Enum<?>> enumType = (Class<Enum<?>>) type; Enum<?>[] enumConstants = enumType.getEnumConstants(); // 解析枚举 List<String> enumDescList = Arrays.stream(enumConstants).map(this::obtainEnumDescription).collect(Collectors.toList()); Object oldValue = ReflectionUtils.getField(parameterDescriptionField, parameterBuilder); parameterBuilder.description((oldValue == null ? "" : oldValue) + buildHtmlUnOrderList(enumDescList)); } /** * 此插件是否支持处理该DocumentationType */ @Override public boolean supports(@NonNull DocumentationType documentationType) { return true; } /** * 获取枚举描述 * * @param enumObj 枚举对象 * * @return 枚举描述 */ private String obtainEnumDescription(@NonNull Enum<?> enumObj) { String name = enumObj.name(); /* * 枚举说明器示例: * * public interface EnumDescriptor { * // 获取枚举项说明 * String obtainDescription(); * } */ if (enumObj instanceof EnumDescriptor) { return name + ":" + ((EnumDescriptor) enumObj).obtainDescription(); } return name; } /** * 构建无序列表html * * @param itemList 列表元素 * * @return 无序列表html */ private String buildHtmlUnOrderList(@Nullable List<String> itemList) { if (CollectionUtils.isEmpty(itemList)) { return ""; } StringBuilder sb = new StringBuilder(); sb.append("
    "); for (String item : itemList) { sb.append("
  • "); sb.append(item); sb.append("
  • "
    ); } sb.append("
"
); return sb.toString(); } } }

第三步:放行相关资源 & 保证启动了knife4j

  • 放行相关资源

    对于管控了权限的微服务,应放行以下资源

    // 需要放行的资源已经定义进上面编写的Knife4jConfig中
    public static String[] RESOURCE_URLS = new String[]{"/webjars/**", "/swagger**", "/v3/api-docs", "/doc.html"};
    
  • 保证启动了knife4j

    # 启动knife4j(注:有时,如果我们不进行此配置,knife4j不会开启)
    # 其实核心是:保证com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration生效即可。如果knife4j怎么也没启动,请debug此类,确保其被加载
    knife4j.enable=true
    # 兼容swagger3
    spring.mvc.pathmatch.matching-strategy=ant_path_matcher
    

网关集成knife4j

编写配置类Knife4jGatewayConfig

import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.StringUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.gateway.config.GatewayProperties;
import org.springframework.cloud.gateway.route.RouteLocator;
import org.springframework.cloud.gateway.support.NameUtils;
import org.springframework.context.annotation.Primary;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Component;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Mono;
import springfox.documentation.swagger.web.SecurityConfiguration;
import springfox.documentation.swagger.web.SecurityConfigurationBuilder;
import springfox.documentation.swagger.web.SwaggerResource;
import springfox.documentation.swagger.web.SwaggerResourcesProvider;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger.web.UiConfigurationBuilder;

import javax.annotation.Resource;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.LinkedHashSet;
import java.util.List;
import java.util.Optional;
import java.util.Set;
import java.util.stream.Collectors;

/**
 * 网关knife4j配置
 *
 * @author JustryDeng 
 * @since 2021.0.1.D
 */
@RestController
public class Knife4jGatewayConfig {
    
    private final SecurityConfiguration securityConfiguration;
    
    private final UiConfiguration uiConfiguration;
    
    private final SwaggerResourceAdapter swaggerResourceAdapter;
    
    public Knife4jGatewayConfig(@Autowired(required = false) SecurityConfiguration securityConfiguration,
                                @Autowired(required = false) UiConfiguration uiConfiguration,
                                SwaggerResourceAdapter swaggerResourceAdapter) {
        this.securityConfiguration = securityConfiguration;
        this.uiConfiguration = uiConfiguration;
        this.swaggerResourceAdapter = swaggerResourceAdapter;
    }
    
    /**
     * 安全配置
     */
    @GetMapping("/swagger-resources/configuration/security")
    public Mono<ResponseEntity<SecurityConfiguration>> securityConfiguration() {
        return Mono.just(new ResponseEntity<>(
                Optional.ofNullable(securityConfiguration).orElse(SecurityConfigurationBuilder.builder().build()), HttpStatus.OK));
    }
    
    /**
     * ui配置
     */
    @GetMapping("/swagger-resources/configuration/ui")
    public Mono<ResponseEntity<UiConfiguration>> uiConfiguration() {
        return Mono.just(new ResponseEntity<>(
                Optional.ofNullable(uiConfiguration).orElse(UiConfigurationBuilder.builder().build()), HttpStatus.OK));
    }
    
    /**
     * 资源配置,自动路由到微服务中的各个服务的api-docs信息
     */
    @GetMapping("/swagger-resources")
    public Mono<ResponseEntity<List<SwaggerResource>>> swaggerResources() {
        return Mono.just(new ResponseEntity<>(swaggerResourceAdapter.get(), HttpStatus.OK));
    }
    
    /**
     * favicon.ico
     */
    @GetMapping("/favicon.ico")
    public Mono<ResponseEntity<?>> favicon() {
        return Mono.just(new ResponseEntity<>(null, HttpStatus.OK));
    }
    
    /**
     * swagger资源适配器
     *
     * @author JustryDeng 
     * @since 2021.0.1.D
     */
    @Slf4j
    @Primary
    @Component
    public static class SwaggerResourceAdapter implements SwaggerResourcesProvider {
        
        /**
         * spring-cloud-gateway是否开启了根据服务发现自动为服务创建router
         */
        @Value("${spring.cloud.gateway.discovery.locator.enabled:false}")
        private boolean autoCreateRouter;
        
        @Value("${spring.application.name:}")
        private String applicationName;
        
        @Resource
        private RouteLocator routeLocator;
        
        @Resource
        private GatewayProperties gatewayProperties;
        
        /**
         * 根据当前所有的微服务路由信息,创建对应的SwaggerResource
         */
        @Override
        public List<SwaggerResource> get() {
            List<SwaggerResource> finalResources;
            Set<String> routes = new LinkedHashSet<>(16);
            // 获取所有路由的id
            routeLocator.getRoutes().subscribe(route -> {
                String routeId = route.getId();
                routeId = routeId.replace("ReactiveCompositeDiscoveryClient_", "");
                routes.add(routeId);
            });
            // 没有开启自动创建路由,那么走配置文件中配置的路由
            if (!autoCreateRouter) {
                finalResources = new ArrayList<>(16);
                gatewayProperties.getRoutes().stream()
                        // 过滤出配置文件中定义的路由
                        .filter(routeDefinition -> routes.contains(routeDefinition.getId())).forEach(route -> {
                            route.getPredicates().stream()
                                    // 过滤出设置有Path Predicate的路由
                                    .filter(predicateDefinition -> ("Path").equalsIgnoreCase(predicateDefinition.getName()))
                                    // 根据路径拼接成api-docs路径,生成SwaggerResource
                                    .forEach(predicateDefinition -> finalResources.add(swaggerResource(route.getId(),
                                            predicateDefinition.getArgs().get(NameUtils.GENERATED_NAME_PREFIX + "0")
                                                    // 如果对应的微服务设置了server.servlet.context-path,那么这里应该是{context-path}/v3/api-docs
                                                    .replace("**", "v3/api-docs"))));
                        });
            } else {
                // 如果对应的微服务设置了server.servlet.context-path,那么这里应该是/{context-path}/v3/api-docs
                finalResources = routes.stream().map(routeId -> swaggerResource(routeId, routeId + "/v3/api-docs")).collect(Collectors.toList());
            }
            List<SwaggerResource> resources = new ArrayList<>(finalResources);
            // resources过滤掉网关的SwaggerResource, 我们一般也不会在网关中编写业务controller
            if (StringUtils.isNotBlank(applicationName)) {
                resources = resources.stream().filter(x -> !applicationName.equalsIgnoreCase(x.getName())).collect(Collectors.toList());
            }
            // 排序
            resources.sort(Comparator.comparing(x -> x.getName().length()));
            return resources;
        }
        
        /**
         * 创建swagger资源
         *
         * @param name
         *            swagger资源名(注:一般对应 {路由id})
         * @param location
         *            swagger资源路径(注:一般对应 {路由id}/v3/api-docs)
         * @return  swagger资源
         */
        private SwaggerResource swaggerResource(String name, String location) {
            // 确保首字符不是/
            location = location.startsWith("/") ? location.substring(1) : location;
            log.info("name:{},location:{}", name, location);
            SwaggerResource swaggerResource = new SwaggerResource();
            swaggerResource.setName(name);
            swaggerResource.setLocation(location + "?group=" + name);
            swaggerResource.setSwaggerVersion("3.0");
            return swaggerResource;
        }
    }
}

测试验证

启动微服务后,访问{网关}/doc.html完成验证

springcloud-gateway集成knife4j(swagger3)_第1张图片

相关资料

  • springboot2集成knife4j(swagger2)
  • springboot2集成knife4j(swagger3)
  • springcloud-gateway集成knife4j(swagger2)
  • 在微服务项目中引入 knife4j
  • 本文已被收录进《程序员成长笔记》 ,笔者JustryDeng

你可能感兴趣的:(swagger3,微服务集成swagger3,微服务集成knife4j,api文档微服务集成)