feat:新增swagger2文档聚合

cloud-common/cloud-common-core/pom.xml

@@ -17,6 +17,12 @@
 
     <dependencies>
 
+        <!-- Swagger -->
+        <dependency>
+            <groupId>io.swagger</groupId>
+            <artifactId>swagger-annotations</artifactId>
+        </dependency>
+
         <!-- SpringCloud Openfeign -->
         <dependency>
             <groupId>org.springframework.cloud</groupId>

cloud-common/cloud-common-swagger/pom.xml

@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>com.muyu</groupId>
+        <artifactId>cloud-server</artifactId>
+        <version>3.6.3</version>
+        <relativePath>../../pom.xml</relativePath>
+    </parent>
+
+    <groupId>com.muyu</groupId>
+    <artifactId>cloud-common-swagger</artifactId>
+    <description>
+        cloud-common-swagger swagger2文档聚合
+    </description>
+    <properties>
+        <maven.compiler.source>17</maven.compiler.source>
+        <maven.compiler.target>17</maven.compiler.target>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+    <dependencies>
+        <!-- SpringBoot Web -->
+        <dependency>
+            <groupId>org.springframework.boot</groupId>
+            <artifactId>spring-boot-starter-web</artifactId>
+        </dependency>
+
+        <!-- Swagger -->
+        <dependency>
+            <groupId>io.springfox</groupId>
+            <artifactId>springfox-swagger2</artifactId>
+            <version>${swagger.fox.version}</version>
+        </dependency>
+
+    </dependencies>
+</project>

cloud-common/cloud-common-swagger/src/main/java/com/muyu/common/swagger/annotation/EnableCustomSwagger2.java

@@ -0,0 +1,10 @@
+package com.muyu.common.swagger.annotation;
+
+/**
+ * @author 袁子龙
+ * @package：com.muyu.common.swagger.annotation
+ * @name：EnableCustomSwagger2
+ * @date：2024/9/29 10:01
+ */
+public @interface EnableCustomSwagger2 {
+}

cloud-common/cloud-common-swagger/src/main/java/com/muyu/common/swagger/config/SwaggerAutoConfiguration.java

@@ -0,0 +1,117 @@
+package com.muyu.common.swagger.config;
+
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.context.annotation.Import;
+import springfox.documentation.builders.ApiInfoBuilder;
+import springfox.documentation.builders.PathSelectors;
+import springfox.documentation.builders.RequestHandlerSelectors;
+import springfox.documentation.service.*;
+import springfox.documentation.spi.DocumentationType;
+import springfox.documentation.spi.service.contexts.SecurityContext;
+import springfox.documentation.spring.web.plugins.ApiSelectorBuilder;
+import springfox.documentation.spring.web.plugins.Docket;
+import springfox.documentation.swagger2.annotations.EnableSwagger2;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+import java.util.function.Predicate;
+
+/**
+ * @author 袁子龙
+ * @package：com.muyu.common.swagger.config
+ * @name：SwaggerAutoConfiguration
+ * @date：2024/9/29 10:07
+ */
+@Configuration
+@EnableSwagger2
+@EnableConfigurationProperties(SwaggerProperties.class)
+@ConditionalOnProperty(name = "swagger.enabled", matchIfMissing = true)
+@Import({SwaggerBeanPostProcessor.class, SwaggerWebConfiguration.class})
+public class SwaggerAutoConfiguration {
+    /**
+     * 默认的排除路径，排除Spring Boot默认的错误处理路径和端点
+     */
+    private static final List<String> DEFAULT_EXCLUDE_PATH = Arrays.asList("/error", "/actuator/**");
+
+    private static final String BASE_PATH = "/**";
+
+    @Bean
+    public Docket api (SwaggerProperties swaggerProperties) {
+        // base-path处理
+        if (swaggerProperties.getBasePath().isEmpty()) {
+            swaggerProperties.getBasePath().add(BASE_PATH);
+        }
+        // noinspection unchecked
+        List<Predicate<String>> basePath = new ArrayList<Predicate<String>>();
+        swaggerProperties.getBasePath().forEach(path -> basePath.add(PathSelectors.ant(path)));
+
+        // exclude-path处理
+        if (swaggerProperties.getExcludePath().isEmpty()) {
+            swaggerProperties.getExcludePath().addAll(DEFAULT_EXCLUDE_PATH);
+        }
+
+        List<Predicate<String>> excludePath = new ArrayList<>();
+        swaggerProperties.getExcludePath().forEach(path -> excludePath.add(PathSelectors.ant(path)));
+
+        ApiSelectorBuilder builder = new Docket(DocumentationType.SWAGGER_2).host(swaggerProperties.getHost())
+                .apiInfo(apiInfo(swaggerProperties)).select()
+                .apis(RequestHandlerSelectors.basePackage(swaggerProperties.getBasePackage()));
+
+        swaggerProperties.getBasePath().forEach(p -> builder.paths(PathSelectors.ant(p)));
+        swaggerProperties.getExcludePath().forEach(p -> builder.paths(PathSelectors.ant(p).negate()));
+
+        return builder.build().securitySchemes(securitySchemes()).securityContexts(securityContexts()).pathMapping("/");
+    }
+
+    /**
+     * 安全模式，这里指定token通过Authorization头请求头传递
+     */
+    private List<SecurityScheme> securitySchemes () {
+        List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
+        apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
+        return apiKeyList;
+    }
+
+    /**
+     * 安全上下文
+     */
+    private List<SecurityContext> securityContexts () {
+        List<SecurityContext> securityContexts = new ArrayList<>();
+        securityContexts.add(
+                SecurityContext.builder()
+                        .securityReferences(defaultAuth())
+                        .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
+                        .build());
+        return securityContexts;
+    }
+
+    /**
+     * 默认的全局鉴权策略
+     *
+     * @return
+     */
+    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;
+    }
+
+    private ApiInfo apiInfo (SwaggerProperties swaggerProperties) {
+        return new ApiInfoBuilder()
+                .title(swaggerProperties.getTitle())
+                .description(swaggerProperties.getDescription())
+                .license(swaggerProperties.getLicense())
+                .licenseUrl(swaggerProperties.getLicenseUrl())
+                .termsOfServiceUrl(swaggerProperties.getTermsOfServiceUrl())
+                .contact(new Contact(swaggerProperties.getContact().getName(), swaggerProperties.getContact().getUrl(), swaggerProperties.getContact().getEmail()))
+                .version(swaggerProperties.getVersion())
+                .build();
+    }
+}

cloud-common/cloud-common-swagger/src/main/java/com/muyu/common/swagger/config/SwaggerBeanPostProcessor.java

@@ -0,0 +1,46 @@
+package com.muyu.common.swagger.config;
+
+import org.springframework.beans.BeansException;
+import org.springframework.beans.factory.config.BeanPostProcessor;
+import org.springframework.util.ReflectionUtils;
+import org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping;
+import springfox.documentation.spring.web.plugins.WebFluxRequestHandlerProvider;
+import springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider;
+
+import java.lang.reflect.Field;
+import java.util.List;
+import java.util.stream.Collectors;
+
+/**
+ * @author 袁子龙
+ * @package：com.muyu.common.swagger.config
+ * @name：SwaggerBeanPostProcessor
+ * @date：2024/9/29 10:07
+ */
+public class SwaggerBeanPostProcessor implements BeanPostProcessor {
+    @Override
+    public Object postProcessAfterInitialization (Object bean, String beanName) throws BeansException {
+        if (bean instanceof WebMvcRequestHandlerProvider || bean instanceof WebFluxRequestHandlerProvider) {
+            customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
+        }
+        return bean;
+    }
+
+    private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings (List<T> mappings) {
+        List<T> copy = mappings.stream().filter(mapping -> mapping.getPatternParser() == null)
+                .collect(Collectors.toList());
+        mappings.clear();
+        mappings.addAll(copy);
+    }
+
+    @SuppressWarnings("unchecked")
+    private List<RequestMappingInfoHandlerMapping> getHandlerMappings (Object bean) {
+        try {
+            Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
+            field.setAccessible(true);
+            return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
+        } catch (IllegalArgumentException | IllegalAccessException e) {
+            throw new IllegalStateException(e);
+        }
+    }
+}

cloud-common/cloud-common-swagger/src/main/java/com/muyu/common/swagger/config/SwaggerProperties.java

@@ -0,0 +1,303 @@
+package com.muyu.common.swagger.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * @author 袁子龙
+ * @package：com.muyu.common.swagger.config
+ * @name：SwaggerProperties
+ * @date：2024/9/29 10:08
+ */
+@ConfigurationProperties("swagger")
+public class SwaggerProperties {
+    /**
+     * 是否开启swagger
+     */
+    private Boolean enabled;
+
+    /**
+     * swagger会解析的包路径
+     **/
+    private String basePackage = "";
+
+    /**
+     * swagger会解析的url规则
+     **/
+    private List<String> basePath = new ArrayList<>();
+
+    /**
+     * 在basePath基础上需要排除的url规则
+     **/
+    private List<String> excludePath = new ArrayList<>();
+
+    /**
+     * 标题
+     **/
+    private String title = "";
+
+    /**
+     * 描述
+     **/
+    private String description = "";
+
+    /**
+     * 版本
+     **/
+    private String version = "";
+
+    /**
+     * 许可证
+     **/
+    private String license = "";
+
+    /**
+     * 许可证URL
+     **/
+    private String licenseUrl = "";
+
+    /**
+     * 服务条款URL
+     **/
+    private String termsOfServiceUrl = "";
+
+    /**
+     * host信息
+     **/
+    private String host = "";
+
+    /**
+     * 联系人信息
+     */
+    private Contact contact = new Contact();
+
+    /**
+     * 全局统一鉴权配置
+     **/
+    private Authorization authorization = new Authorization();
+
+    public Boolean getEnabled () {
+        return enabled;
+    }
+
+    public void setEnabled (Boolean enabled) {
+        this.enabled = enabled;
+    }
+
+    public String getBasePackage () {
+        return basePackage;
+    }
+
+    public void setBasePackage (String basePackage) {
+        this.basePackage = basePackage;
+    }
+
+    public List<String> getBasePath () {
+        return basePath;
+    }
+
+    public void setBasePath (List<String> basePath) {
+        this.basePath = basePath;
+    }
+
+    public List<String> getExcludePath () {
+        return excludePath;
+    }
+
+    public void setExcludePath (List<String> excludePath) {
+        this.excludePath = excludePath;
+    }
+
+    public String getTitle () {
+        return title;
+    }
+
+    public void setTitle (String title) {
+        this.title = title;
+    }
+
+    public String getDescription () {
+        return description;
+    }
+
+    public void setDescription (String description) {
+        this.description = description;
+    }
+
+    public String getVersion () {
+        return version;
+    }
+
+    public void setVersion (String version) {
+        this.version = version;
+    }
+
+    public String getLicense () {
+        return license;
+    }
+
+    public void setLicense (String license) {
+        this.license = license;
+    }
+
+    public String getLicenseUrl () {
+        return licenseUrl;
+    }
+
+    public void setLicenseUrl (String licenseUrl) {
+        this.licenseUrl = licenseUrl;
+    }
+
+    public String getTermsOfServiceUrl () {
+        return termsOfServiceUrl;
+    }
+
+    public void setTermsOfServiceUrl (String termsOfServiceUrl) {
+        this.termsOfServiceUrl = termsOfServiceUrl;
+    }
+
+    public String getHost () {
+        return host;
+    }
+
+    public void setHost (String host) {
+        this.host = host;
+    }
+
+    public Contact getContact () {
+        return contact;
+    }
+
+    public void setContact (Contact contact) {
+        this.contact = contact;
+    }
+
+    public Authorization getAuthorization () {
+        return authorization;
+    }
+
+    public void setAuthorization (Authorization authorization) {
+        this.authorization = authorization;
+    }
+
+    public static class Contact {
+        /**
+         * 联系人
+         **/
+        private String name = "";
+        /**
+         * 联系人url
+         **/
+        private String url = "";
+        /**
+         * 联系人email
+         **/
+        private String email = "";
+
+        public String getName () {
+            return name;
+        }
+
+        public void setName (String name) {
+            this.name = name;
+        }
+
+        public String getUrl () {
+            return url;
+        }
+
+        public void setUrl (String url) {
+            this.url = url;
+        }
+
+        public String getEmail () {
+            return email;
+        }
+
+        public void setEmail (String email) {
+            this.email = email;
+        }
+    }
+
+    public static class Authorization {
+        /**
+         * 鉴权策略ID，需要和SecurityReferences ID保持一致
+         */
+        private String name = "";
+
+        /**
+         * 需要开启鉴权URL的正则
+         */
+        private String authRegex = "^.*$";
+
+        /**
+         * 鉴权作用域列表
+         */
+        private List<AuthorizationScope> authorizationScopeList = new ArrayList<>();
+
+        private List<String> tokenUrlList = new ArrayList<>();
+
+        public String getName () {
+            return name;
+        }
+
+        public void setName (String name) {
+            this.name = name;
+        }
+
+        public String getAuthRegex () {
+            return authRegex;
+        }
+
+        public void setAuthRegex (String authRegex) {
+            this.authRegex = authRegex;
+        }
+
+        public List<AuthorizationScope> getAuthorizationScopeList () {
+            return authorizationScopeList;
+        }
+
+        public void setAuthorizationScopeList (List<AuthorizationScope> authorizationScopeList) {
+            this.authorizationScopeList = authorizationScopeList;
+        }
+
+        public List<String> getTokenUrlList () {
+            return tokenUrlList;
+        }
+
+        public void setTokenUrlList (List<String> tokenUrlList) {
+            this.tokenUrlList = tokenUrlList;
+        }
+    }
+
+    public static class AuthorizationScope {
+        /**
+         * 作用域名称
+         */
+        private String scope = "";
+
+        /**
+         * 作用域描述
+         */
+        private String description = "";
+
+        public String getScope () {
+            return scope;
+        }
+
+        public void setScope (String scope) {
+            this.scope = scope;
+        }
+
+        public String getDescription () {
+            return description;
+        }
+
+        public void setDescription (String description) {
+            this.description = description;
+        }
+    }
+}
+

cloud-common/cloud-common-swagger/src/main/java/com/muyu/common/swagger/config/SwaggerWebConfiguration.java

@@ -0,0 +1,19 @@
+package com.muyu.common.swagger.config;
+
+import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+/**
+ * @author 袁子龙
+ * @package：com.muyu.common.swagger.config
+ * @name：SwaggerWebConfiguration
+ * @date：2024/9/29 10:08
+ */
+public class SwaggerWebConfiguration implements WebMvcConfigurer {
+    @Override
+    public void addResourceHandlers (ResourceHandlerRegistry registry) {
+        /** swagger-ui 地址 */
+        registry.addResourceHandler("/swagger-ui/**")
+                .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
+    }
+}

cloud-common/pom.xml

@@ -21,6 +21,7 @@
         <module>cloud-common-xxl</module>
         <module>cloud-common-rabbit</module>
         <module>cloud-common-saas</module>
+        <module>cloud-common-swagger</module>
     </modules>
 
     <artifactId>cloud-common</artifactId>