commit swagger

README.md

@@ -0,0 +1,9 @@
+# swagger 集成 2.9.2
+## spring boot 2.7.15 cloud 2021.0.8
+
+# swagger document
+## get yaml for /resources/openapi-config.yaml
+### 示例:http://localhost:8082/v3/api-docs
+
+# swagger接口地址
+## http://localhost:8082/doc.html#/home

pom.xml

@@ -21,6 +21,8 @@
         <mybatisPlus.version>3.4.1</mybatisPlus.version>
         <mybatis.version>2.1.4</mybatis.version>
         <fastjson.version>1.2.83</fastjson.version>
+        <springdoc.version>1.6.14</springdoc.version>
+        <knife4j.version>4.0.0</knife4j.version>
     </properties>
     <dependencies>
         <!-- 达梦数据库驱动 -->
@@ -54,6 +56,38 @@
             <groupId>org.projectlombok</groupId>
             <artifactId>lombok</artifactId>
         </dependency>
+        <!-- swagger -->
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-webmvc-core</artifactId>
+            <version>1.6.9</version>
+        </dependency>
+        <!--<dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-security</artifactId>
+            <version>1.6.9</version>
+        </dependency>-->
+        <dependency>
+            <groupId>io.swagger.core.v3</groupId>
+            <artifactId>swagger-annotations</artifactId>
+            <version>2.2.0</version>
+        </dependency>
+        <dependency>
+            <groupId>org.springframework.cloud</groupId>
+            <artifactId>spring-cloud-commons</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.springdoc</groupId>
+            <artifactId>springdoc-openapi-ui</artifactId>
+            <version>${springdoc.version}</version>
+        </dependency>
+        <dependency>
+            <groupId>com.github.xiaoymin</groupId>
+            <artifactId>knife4j-openapi3-spring-boot-starter</artifactId>
+            <version>${knife4j.version}</version>
+        </dependency>
+        <!-- end -->
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-web</artifactId>

src/main/java/com/unis/VsualizationReportApplication.java

@@ -1,9 +1,11 @@
 package com.unis;
 
+import com.unis.common.swagger.annotation.EnableOpenApi;
 import org.mybatis.spring.annotation.MapperScan;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 
+@EnableOpenApi(value = "admin", isMicro = false)
 @SpringBootApplication
 @MapperScan({
         "com.unis.*.mapper"

src/main/java/com/unis/common/factory/YamlPropertySourceFactory.java

@@ -0,0 +1,44 @@
+package com.unis.common.factory;
+
+import org.springframework.beans.factory.config.YamlPropertiesFactoryBean;
+import org.springframework.core.env.PropertiesPropertySource;
+import org.springframework.core.env.PropertySource;
+import org.springframework.core.io.support.EncodedResource;
+import org.springframework.core.io.support.PropertySourceFactory;
+import org.springframework.lang.Nullable;
+
+import java.io.FileNotFoundException;
+import java.io.IOException;
+import java.util.Properties;
+
+/**
+ * @author avenue
+ * @date 2022/3/29
+ * <p>
+ * 读取自定义 yaml 文件工厂类
+ */
+public class YamlPropertySourceFactory implements PropertySourceFactory {
+
+    @Override
+    public PropertySource<?> createPropertySource(@Nullable String name, EncodedResource resource) throws IOException {
+        Properties propertiesFromYaml = loadYamlIntoProperties(resource);
+        String sourceName = name != null ? name : resource.getResource().getFilename();
+        return new PropertiesPropertySource(sourceName, propertiesFromYaml);
+    }
+
+    private Properties loadYamlIntoProperties(EncodedResource resource) throws FileNotFoundException {
+        try {
+            YamlPropertiesFactoryBean factory = new YamlPropertiesFactoryBean();
+            factory.setResources(resource.getResource());
+            factory.afterPropertiesSet();
+            return factory.getObject();
+        }
+        catch (IllegalStateException e) {
+            Throwable cause = e.getCause();
+            if (cause instanceof FileNotFoundException)
+                throw (FileNotFoundException) e.getCause();
+            throw e;
+        }
+    }
+
+}

src/main/java/com/unis/common/swagger/annotation/EnableOpenApi.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright (c) 2020 pig4cloud Authors. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.unis.common.swagger.annotation;
+
+import com.unis.common.factory.YamlPropertySourceFactory;
+import com.unis.common.swagger.config.OpenAPIDefinitionImportSelector;
+import com.unis.common.swagger.support.SwaggerProperties;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Import;
+import org.springframework.context.annotation.PropertySource;
+
+import java.lang.annotation.*;
+
+/**
+ * 开启 pig spring doc
+ *
+ * @author avenue
+ * @date 2022-03-26
+ */
+@Target({ ElementType.TYPE })
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@Inherited
+@EnableConfigurationProperties(SwaggerProperties.class)
+@Import({ OpenAPIDefinitionImportSelector.class })
+@PropertySource(value = "classpath:openapi-config.yaml", factory = YamlPropertySourceFactory.class)
+public @interface EnableOpenApi {
+
+    /**
+     * 网关路由前缀
+     * @return String
+     */
+    String value() default "";
+
+    /**
+     * 是否是微服务架构
+     * @return true
+     */
+    boolean isMicro() default true;
+
+}

src/main/java/com/unis/common/swagger/config/OpenAPIDefinition.java

@@ -0,0 +1,90 @@
+/*
+ *    Copyright (c) 2018-2025, avenue All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * Redistributions of source code must retain the above copyright notice,
+ * this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ * Neither the name of the pig4cloud.com developer nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ * Author: avenue
+ */
+package com.unis.common.swagger.config;
+
+import com.unis.common.swagger.support.SwaggerProperties;
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.security.OAuthFlow;
+import io.swagger.v3.oas.models.security.OAuthFlows;
+import io.swagger.v3.oas.models.security.Scopes;
+import io.swagger.v3.oas.models.security.SecurityScheme;
+import io.swagger.v3.oas.models.servers.Server;
+import lombok.RequiredArgsConstructor;
+import lombok.Setter;
+import org.springframework.beans.BeansException;
+import org.springframework.beans.factory.InitializingBean;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.ApplicationContext;
+import org.springframework.context.ApplicationContextAware;
+import org.springframework.http.HttpHeaders;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * swagger配置
+ *
+ * <p>
+ * 禁用方法1：使用注解@Profile({"dev","test"})
+ *
+ * 表示在开发或测试环境开启，而在生产关闭。（推荐使用） 禁用方法2：使用注解@ConditionalOnProperty(name = "swagger.enable",
+ *
+ * havingValue = "true") 然后在测试配置或者开发配置中添加swagger.enable=true即可开启，生产环境不填则默认关闭Swagger.
+ * </p>
+ *
+ * @author avenue
+ */
+@RequiredArgsConstructor
+@ConditionalOnProperty(name = "swagger.enabled", matchIfMissing = true)
+public class OpenAPIDefinition extends OpenAPI implements InitializingBean, ApplicationContextAware {
+
+    @Setter
+    private String path;
+
+    private ApplicationContext applicationContext;
+
+    private SecurityScheme securityScheme(SwaggerProperties swaggerProperties) {
+        OAuthFlow clientCredential = new OAuthFlow();
+        clientCredential.setTokenUrl(swaggerProperties.getTokenUrl());
+        clientCredential.setScopes(new Scopes().addString(swaggerProperties.getScope(), swaggerProperties.getScope()));
+        OAuthFlows oauthFlows = new OAuthFlows();
+        oauthFlows.password(clientCredential);
+        SecurityScheme securityScheme = new SecurityScheme();
+        securityScheme.setType(SecurityScheme.Type.OAUTH2);
+        securityScheme.setFlows(oauthFlows);
+        return securityScheme;
+    }
+
+    @Override
+    public void afterPropertiesSet() throws Exception {
+        SwaggerProperties swaggerProperties = applicationContext.getBean(SwaggerProperties.class);
+        this.info(new Info().title(swaggerProperties.getTitle()));
+        // oauth2.0 password
+        this.schemaRequirement(HttpHeaders.AUTHORIZATION, this.securityScheme(swaggerProperties));
+        // servers
+        List<Server> serverList = new ArrayList<>();
+        serverList.add(new Server().url(swaggerProperties.getGateway() + "/" + path));
+        this.servers(serverList);
+    }
+
+    @Override
+    public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
+        this.applicationContext = applicationContext;
+    }
+
+}

src/main/java/com/unis/common/swagger/config/OpenAPIDefinitionImportSelector.java

@@ -0,0 +1,47 @@
+package com.unis.common.swagger.config;
+
+import com.unis.common.swagger.annotation.EnableOpenApi;
+import org.springframework.beans.factory.support.BeanDefinitionBuilder;
+import org.springframework.beans.factory.support.BeanDefinitionRegistry;
+import org.springframework.context.annotation.ImportBeanDefinitionRegistrar;
+import org.springframework.core.type.AnnotationMetadata;
+
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * openapi 配置类
+ *
+ * @author avenue
+ * @date 2023/1/1
+ */
+public class OpenAPIDefinitionImportSelector implements ImportBeanDefinitionRegistrar {
+
+    @Override
+    public void registerBeanDefinitions(AnnotationMetadata metadata, BeanDefinitionRegistry registry) {
+
+        Map<String, Object> annotationAttributes = metadata.getAnnotationAttributes(EnableOpenApi.class.getName(),
+                true);
+        Object value = annotationAttributes.get("value");
+        if (Objects.isNull(value)) {
+            return;
+        }
+
+        BeanDefinitionBuilder definition = BeanDefinitionBuilder.genericBeanDefinition(OpenAPIDefinition.class);
+        definition.addPropertyValue("path", value);
+
+        registry.registerBeanDefinition("openAPIDefinition", definition.getBeanDefinition());
+
+        // 如果是微服务架构则，引入了服务发现声明相关的元数据配置
+        Object isMicro = annotationAttributes.getOrDefault("isMicro", true);
+        if (isMicro.equals(false)) {
+            return;
+        }
+
+        BeanDefinitionBuilder openAPIMetadata = BeanDefinitionBuilder
+                .genericBeanDefinition(OpenAPIMetadataConfiguration.class);
+        openAPIMetadata.addPropertyValue("path", value);
+        registry.registerBeanDefinition("openAPIMetadata", openAPIMetadata.getBeanDefinition());
+    }
+
+}

src/main/java/com/unis/common/swagger/config/OpenAPIMetadataConfiguration.java

@@ -0,0 +1,32 @@
+package com.unis.common.swagger.config;
+
+import lombok.Setter;
+import org.springframework.beans.BeansException;
+import org.springframework.beans.factory.InitializingBean;
+import org.springframework.cloud.client.ServiceInstance;
+import org.springframework.context.ApplicationContext;
+import org.springframework.context.ApplicationContextAware;
+
+/**
+ * @author avenue
+ * @date 2023/1/4
+ */
+public class OpenAPIMetadataConfiguration implements InitializingBean, ApplicationContextAware {
+
+    private ApplicationContext applicationContext;
+
+    @Setter
+    private String path;
+
+    @Override
+    public void afterPropertiesSet() throws Exception {
+        ServiceInstance serviceInstance = applicationContext.getBean(ServiceInstance.class);
+        serviceInstance.getMetadata().put("spring-doc", path);
+    }
+
+    @Override
+    public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
+        this.applicationContext = applicationContext;
+    }
+
+}

src/main/java/com/unis/common/swagger/support/SwaggerProperties.java

@@ -0,0 +1,86 @@
+/*
+ *    Copyright (c) 2018-2025, avenue All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * Redistributions of source code must retain the above copyright notice,
+ * this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ * Neither the name of the pig4cloud.com developer nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ * Author: avenue
+ */
+package com.unis.common.swagger.support;
+
+import lombok.Data;
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * SwaggerProperties
+ *
+ * @author avenue
+ * @date 2018/7/25 14:00
+ */
+@Data
+@ConfigurationProperties("swagger")
+public class SwaggerProperties {
+
+    /**
+     * 是否开启swagger
+     */
+    private Boolean enabled = true;
+
+    /**
+     * swagger会解析的包路径
+     **/
+    private String basePackage = "";
+
+    /**
+     * swagger会解析的url规则
+     **/
+    private List<String> basePath = new ArrayList<>();
+
+    /**
+     * 在basePath基础上需要排除的url规则
+     **/
+    private List<String> excludePath = new ArrayList<>();
+
+    /**
+     * 需要排除的服务
+     */
+    private List<String> ignoreProviders = new ArrayList<>();
+
+    /**
+     * 标题
+     **/
+    private String title = "";
+
+    /**
+     * 网关
+     */
+    private String gateway;
+
+    /**
+     * 获取token
+     */
+    private String tokenUrl;
+
+    /**
+     * 作用域
+     */
+    private String scope;
+
+    /**
+     * 服务转发配置
+     */
+    private Map<String, String> services;
+
+}

src/main/resources/application.yml

@@ -1,5 +1,7 @@
 server:
   port: 8082
+  servlet:
+    context-path: /
   tomcat:
     uri-encoding: UTF-8
 spring:
@@ -49,4 +51,21 @@ mybatis-plus:
   configuration:
     call-setters-on-nulls: true
     # console show sql
-    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
+    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
+## spring security 配置
+security:
+  oauth2:
+    client:
+      client-id: ENC(ltJPpR50wT0oIY9kfOe1Iw==)
+      client-secret: ENC(ltJPpR50wT0oIY9kfOe1Iw==)
+      scope: server
+      ignore-urls:
+        - /webjars/**
+        - /v3/api-docs/**
+        - /doc.html
+        - /swagger-resources
+        - /css/**
+        - /error
+        - /druid/**
+        - /actuator/**
+        - /code/**

src/main/resources/openapi-config.yaml

@@ -0,0 +1,7 @@
+# swagger 配置
+swagger:
+  enabled: true
+  title: avenue Swagger API
+  gateway: http://${GATEWAY-HOST:avenue-gateway}:${GATEWAY-PORT:9999}
+  token-url: ${swagger.gateway}/auth/oauth2/token
+  scope: server