feat: 修改部分 swagger 注解

yudao-framework/yudao-spring-boot-starter-web/src/main/java/cn/iocoder/yudao/framework/swagger/config/SwaggerProperties.java

@@ -35,9 +35,26 @@ public class SwaggerProperties {
     @NotEmpty(message = "版本不能为空")
     private String version;
     /**
-     * 扫描的包
+     * url
      */
     @NotEmpty(message = "扫描的 package 不能为空")
-    private String basePackage;
+    private String url;
+    /**
+     * email
+     */
+    @NotEmpty(message = "扫描的 email 不能为空")
+    private String email;
+
+    /**
+     * license
+     */
+    @NotEmpty(message = "扫描的 license 不能为空")
+    private String license;
+
+    /**
+     * license-url
+     */
+    @NotEmpty(message = "扫描的 license-url 不能为空")
+    private String licenseUrl;
 
 }

yudao-framework/yudao-spring-boot-starter-web/src/main/java/cn/iocoder/yudao/framework/swagger/config/YudaoSwaggerAutoConfiguration.java

@@ -1,126 +1,155 @@
 package cn.iocoder.yudao.framework.swagger.config;
 
-import cn.iocoder.yudao.framework.swagger.core.SpringFoxHandlerProviderBeanPostProcessor;
-import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
+import io.swagger.v3.oas.models.Components;
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Contact;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.info.License;
+import io.swagger.v3.oas.models.media.IntegerSchema;
+import io.swagger.v3.oas.models.media.StringSchema;
+import io.swagger.v3.oas.models.parameters.Parameter;
+import io.swagger.v3.oas.models.security.SecurityRequirement;
+import io.swagger.v3.oas.models.security.SecurityScheme;
+import org.springdoc.core.*;
+import org.springdoc.core.customizers.OpenApiBuilderCustomizer;
+import org.springdoc.core.customizers.ServerBaseUrlCustomizer;
+import org.springdoc.core.providers.JavadocProvider;
 import org.springframework.boot.autoconfigure.AutoConfiguration;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.context.annotation.Bean;
 import org.springframework.http.HttpHeaders;
-import springfox.documentation.builders.ApiInfoBuilder;
-import springfox.documentation.builders.ParameterBuilder;
-import springfox.documentation.builders.PathSelectors;
-import springfox.documentation.schema.ModelRef;
-import springfox.documentation.service.*;
-import springfox.documentation.spi.DocumentationType;
-import springfox.documentation.spi.service.contexts.SecurityContext;
-import springfox.documentation.spring.web.plugins.Docket;
-import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
 
-import java.util.ArrayList;
-import java.util.Collections;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
+import java.util.Optional;
 
 import static cn.iocoder.yudao.framework.web.core.util.WebFrameworkUtils.HEADER_TENANT_ID;
-import static springfox.documentation.builders.RequestHandlerSelectors.basePackage;
 
 /**
- * Swagger2 自动配置类
+ * Swagger 自动配置类，基于 OpenAPI + Springdoc 实现。
+ *
+ * 友情提示：
+ * 1. Springdoc 文档地址：<a href="https://github.com/springdoc/springdoc-openapi">仓库</a>
+ * 2. Swagger 规范，于 2015 更名为 OpenAPI 规范，本质是一个东西
  *
  * @author 芋道源码
  */
 @AutoConfiguration
-@EnableSwagger2WebMvc
-@EnableKnife4j
-@ConditionalOnClass({Docket.class, ApiInfoBuilder.class})
-// 允许使用 swagger.enable=false 禁用 Swagger
-@ConditionalOnProperty(prefix = "yudao.swagger", value = "enable", matchIfMissing = true)
+@ConditionalOnClass({OpenAPI.class})
 @EnableConfigurationProperties(SwaggerProperties.class)
+@ConditionalOnProperty(prefix = "springdoc.api-docs", name = "enabled", havingValue = "true", matchIfMissing = true) // 设置为 false 时，禁用
 public class YudaoSwaggerAutoConfiguration {
 
-    @Bean
-    public SpringFoxHandlerProviderBeanPostProcessor springFoxHandlerProviderBeanPostProcessor() {
-        return new SpringFoxHandlerProviderBeanPostProcessor();
-    }
+    // ========== 全局 OpenAPI 配置 ==========
 
     @Bean
-    public Docket createRestApi(SwaggerProperties properties) {
-        // 创建 Docket 对象
-        return new Docket(DocumentationType.SWAGGER_2)
-                // ① 用来创建该 API 的基本信息，展示在文档的页面中（自定义展示的信息）
-                .apiInfo(apiInfo(properties))
-                // ② 设置扫描指定 package 包下的
-                .select()
-                .apis(basePackage(properties.getBasePackage()))
-//                .apis(basePackage("cn.iocoder.yudao.module.system")) // 可用于 swagger 无法展示时使用
-                .paths(PathSelectors.any())
-                .build()
-                // ③ 安全上下文（认证）
-                .securitySchemes(securitySchemes())
-                .securityContexts(securityContexts())
-                // ④ 全局参数（多租户 header）
-                .globalOperationParameters(globalRequestParameters());
+    public OpenAPI createApi(SwaggerProperties properties) {
+        Map<String, SecurityScheme> securitySchemas = buildSecuritySchemes();
+        OpenAPI openAPI = new OpenAPI()
+                // 接口信息
+                .info(buildInfo(properties))
+                // 接口安全配置
+                .components(new Components().securitySchemes(securitySchemas))
+                .addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION));
+        securitySchemas.keySet().forEach(key -> openAPI.addSecurityItem(new SecurityRequirement().addList(key)));
+        return openAPI;
     }
 
-    // ========== apiInfo ==========
-
     /**
      * API 摘要信息
      */
-    private static ApiInfo apiInfo(SwaggerProperties properties) {
-        return new ApiInfoBuilder()
+    private Info buildInfo(SwaggerProperties properties) {
+        return new Info()
                 .title(properties.getTitle())
                 .description(properties.getDescription())
-                .contact(new Contact(properties.getAuthor(), null, null))
                 .version(properties.getVersion())
-                .build();
+                .contact(new Contact().name(properties.getAuthor()).url(properties.getUrl()).email(properties.getEmail()))
+                .license(new License().name(properties.getLicense()).url(properties.getLicenseUrl()));
     }
 
-    // ========== securitySchemes ==========
-
     /**
      * 安全模式，这里配置通过请求头 Authorization 传递 token 参数
      */
-    private static List<SecurityScheme> securitySchemes() {
-        return Collections.singletonList(new ApiKey(HttpHeaders.AUTHORIZATION, "Authorization", "header"));
+    private Map<String, SecurityScheme> buildSecuritySchemes() {
+        Map<String, SecurityScheme> securitySchemes = new HashMap<>();
+        SecurityScheme securityScheme = new SecurityScheme()
+                .type(SecurityScheme.Type.APIKEY) // 类型
+                .name(HttpHeaders.AUTHORIZATION) // 请求头的 name
+                .in(SecurityScheme.In.HEADER); // token 所在位置
+        securitySchemes.put(HttpHeaders.AUTHORIZATION, securityScheme);
+        return securitySchemes;
     }
 
     /**
-     * 安全上下文
-     *
-     * @see #securitySchemes()
-     * @see #authorizationScopes()
+     * 自定义 OpenAPI 处理器
      */
-    private static List<SecurityContext> securityContexts() {
-        return Collections.singletonList(SecurityContext.builder()
-                .securityReferences(securityReferences())
-                // 通过 PathSelectors.regex("^(?!auth).*$")，排除包含 "auth" 的接口不需要使用securitySchemes
-                .forPaths(PathSelectors.regex("^(?!auth).*$"))
-                .build());
+    @Bean
+    public OpenAPIService openApiBuilder(Optional<OpenAPI> openAPI,
+                                         SecurityService securityParser,
+                                         SpringDocConfigProperties springDocConfigProperties,
+                                         PropertyResolverUtils propertyResolverUtils,
+                                         Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomizers,
+                                         Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomizers,
+                                         Optional<JavadocProvider> javadocProvider) {
+
+        return new OpenAPIService(openAPI, securityParser, springDocConfigProperties,
+                propertyResolverUtils, openApiBuilderCustomizers, serverBaseUrlCustomizers, javadocProvider);
     }
 
-    private static List<SecurityReference> securityReferences() {
-        return Collections.singletonList(new SecurityReference(HttpHeaders.AUTHORIZATION, authorizationScopes()));
+    // ========== 分组 OpenAPI 配置 ==========
+
+    /**
+     * 所有模块的 API 分组
+     */
+    @Bean
+    public GroupedOpenApi allGroupedOpenApi() {
+        return buildGroupedOpenApi("all", "");
     }
 
-    private static AuthorizationScope[] authorizationScopes() {
-        return new AuthorizationScope[]{new AuthorizationScope("global", "accessEverything")};
+    public static GroupedOpenApi buildGroupedOpenApi(String group) {
+        return buildGroupedOpenApi(group, group);
     }
 
-    // ========== globalRequestParameters ==========
+    public static GroupedOpenApi buildGroupedOpenApi(String group, String path) {
+        return GroupedOpenApi.builder()
+                .group(group)
+                .pathsToMatch("/admin-api/" + path + "/**", "/app-api/" + path + "/**")
+                .addOperationCustomizer((operation, handlerMethod) -> operation
+                        .addParametersItem(buildTenantHeaderParameter())
+                        .addParametersItem(buildSecurityHeaderParameter()))
+                .build();
+    }
 
-    private static List<Parameter> globalRequestParameters() {
-        List<Parameter> tenantParameter = new ArrayList<>();
-        tenantParameter.add(new ParameterBuilder()
-                .name(HEADER_TENANT_ID)
-                .description("租户编号")
-                .modelRef(new ModelRef("long"))
-                .defaultValue("1")
-                .parameterType("header")
-                .required(true)
-                .build());
-        return tenantParameter;
+    /**
+     * 构建 Tenant 租户编号请求头参数
+     *
+     * @return 多租户参数
+     */
+    private static Parameter buildTenantHeaderParameter() {
+        return new Parameter()
+                .name(HEADER_TENANT_ID) // header 名
+                .description("租户编号") // 描述
+                .in(String.valueOf(SecurityScheme.In.HEADER)) // 请求 header
+                .schema(new IntegerSchema()._default(1L).name(HEADER_TENANT_ID).description("租户编号")); // 默认：使用租户编号为 1
+    }
+
+    /**
+     * 构建 Authorization 认证请求头参数
+     *
+     * 解决 Knife4j <a href="https://gitee.com/xiaoym/knife4j/issues/I69QBU">Authorize 未生效，请求header里未包含参数</a>
+     *
+     * @return 认证参数
+     */
+    private static Parameter buildSecurityHeaderParameter() {
+        return new Parameter()
+                .name(HttpHeaders.AUTHORIZATION) // header 名
+                .description("认证 Token") // 描述
+                .in(String.valueOf(SecurityScheme.In.HEADER)) // 请求 header
+                .schema(new StringSchema()._default("Bearer test1").name(HEADER_TENANT_ID).description("认证 Token")); // 默认：使用用户编号为 1
     }
 
 }
+

yudao-framework/yudao-spring-boot-starter-web/src/main/java/cn/iocoder/yudao/framework/swagger/core/SpringFoxHandlerProviderBeanPostProcessor.java

@@ -1,42 +1,42 @@
-package cn.iocoder.yudao.framework.swagger.core;
-
-import cn.hutool.core.util.ReflectUtil;
-import cn.iocoder.yudao.framework.common.util.collection.CollectionUtils;
-import org.springframework.beans.BeansException;
-import org.springframework.beans.factory.config.BeanPostProcessor;
-import org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping;
-import springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider;
-
-import java.util.List;
-
-/**
- * 解决 SpringFox 与 SpringBoot 2.6.x 不兼容的问题
- * 该问题对应的 issue 为 https://github.com/springfox/springfox/issues/3462
- *
- * @author 芋道源码
- */
-public class SpringFoxHandlerProviderBeanPostProcessor implements BeanPostProcessor {
-
-    @Override
-    public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
-        if (bean instanceof WebMvcRequestHandlerProvider) {
-            customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
-        }
-        return bean;
-    }
-
-    private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) {
-        // 移除，只保留 patternParser
-        List<T> copy = CollectionUtils.filterList(mappings, mapping -> mapping.getPatternParser() == null);
-        // 添加到 mappings 中
-        mappings.clear();
-        mappings.addAll(copy);
-    }
-
-    @SuppressWarnings("unchecked")
-    private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
-        return (List<RequestMappingInfoHandlerMapping>)
-                ReflectUtil.getFieldValue(bean, "handlerMappings");
-    }
-
-}
+//package cn.iocoder.yudao.framework.swagger.core;
+//
+//import cn.hutool.core.util.ReflectUtil;
+//import cn.iocoder.yudao.framework.common.util.collection.CollectionUtils;
+//import org.springframework.beans.BeansException;
+//import org.springframework.beans.factory.config.BeanPostProcessor;
+//import org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping;
+//import springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider;
+//
+//import java.util.List;
+//
+///**
+// * 解决 SpringFox 与 SpringBoot 2.6.x 不兼容的问题
+// * 该问题对应的 issue 为 https://github.com/springfox/springfox/issues/3462
+// *
+// * @author 芋道源码
+// */
+//public class SpringFoxHandlerProviderBeanPostProcessor implements BeanPostProcessor {
+//
+//    @Override
+//    public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
+//        if (bean instanceof WebMvcRequestHandlerProvider) {
+//            customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
+//        }
+//        return bean;
+//    }
+//
+//    private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) {
+//        // 移除，只保留 patternParser
+//        List<T> copy = CollectionUtils.filterList(mappings, mapping -> mapping.getPatternParser() == null);
+//        // 添加到 mappings 中
+//        mappings.clear();
+//        mappings.addAll(copy);
+//    }
+//
+//    @SuppressWarnings("unchecked")
+//    private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
+//        return (List<RequestMappingInfoHandlerMapping>)
+//                ReflectUtil.getFieldValue(bean, "handlerMappings");
+//    }
+//
+//}

yudao-framework/yudao-spring-boot-starter-web/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

@@ -1,5 +1,6 @@
-cn.iocoder.yudao.framework.apilog.config.YudaoApiLogRpcAutoConfiguration
 cn.iocoder.yudao.framework.apilog.config.YudaoApiLogAutoConfiguration
 cn.iocoder.yudao.framework.jackson.config.YudaoJacksonAutoConfiguration
+com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration
 cn.iocoder.yudao.framework.swagger.config.YudaoSwaggerAutoConfiguration
 cn.iocoder.yudao.framework.web.config.YudaoWebAutoConfiguration
+cn.iocoder.yudao.framework.xss.config.YudaoXssAutoConfiguration