spring doc：增加模块分组

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

@@ -6,6 +6,7 @@ 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;
@@ -27,8 +28,11 @@ import java.util.Optional;
 import static cn.iocoder.yudao.framework.web.core.util.WebFrameworkUtils.HEADER_TENANT_ID;
 
 /**
- * springdoc 自动配置类
- * 使用 knife4j.enable=false 禁用 Swagger
+ * Swagger 自动配置类，基于 OpenAPI + Springdoc 实现。
+ *
+ * 友情提示：
+ * 1. Springdoc 文档地址：<a href="https://github.com/springdoc/springdoc-openapi">仓库</a>
+ * 2. Swagger 规范，于 2015 更名为 OpenAPI 规范，本质是一个东西
  *
  * @author 芋道源码
  */
@@ -37,53 +41,21 @@ import static cn.iocoder.yudao.framework.web.core.util.WebFrameworkUtils.HEADER_
 @EnableConfigurationProperties(SwaggerProperties.class)
 public class YudaoSwaggerAutoConfiguration {
 
+    // ========== 全局 OpenAPI 配置 ==========
+
     @Bean
     public OpenAPI createApi(SwaggerProperties properties) {
-        Map<String, SecurityScheme> maps = securityScheme();
+        Map<String, SecurityScheme> securitySchemas = buildSecuritySchemes();
         OpenAPI openAPI = new OpenAPI()
+                // 接口信息
                 .info(buildInfo(properties))
-                .components(new Components().securitySchemes(maps))
+                // 接口安全配置
+                .components(new Components().securitySchemes(securitySchemas))
                 .addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION));
-        maps.keySet().forEach(key -> openAPI.addSecurityItem(new SecurityRequirement().addList(key)));
+        securitySchemas.keySet().forEach(key -> openAPI.addSecurityItem(new SecurityRequirement().addList(key)));
         return openAPI;
     }
 
-    /**
-     * 自定义 openapi 处理器
-     */
-    @Bean
-    public OpenAPIService openApiBuilder(Optional<OpenAPI> openAPI,
-                                         SecurityService securityParser,
-                                         SpringDocConfigProperties springDocConfigProperties,
-                                         PropertyResolverUtils propertyResolverUtils,
-                                         Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomisers,
-                                         Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomisers,
-                                         Optional<JavadocProvider> javadocProvider) {
-        return new OpenAPIService(openAPI, securityParser, springDocConfigProperties, propertyResolverUtils, openApiBuilderCustomisers, serverBaseUrlCustomisers, javadocProvider);
-    }
-
-    @Bean
-    public GroupedOpenApi appApi() {
-        return GroupedOpenApi.builder()
-                .group("app")
-                .addOperationCustomizer((operation, handlerMethod) ->
-                        operation.addParametersItem(globalHeaderParameter())
-                )
-                .pathsToMatch("/app-api/**")
-                .build();
-    }
-
-    @Bean
-    public GroupedOpenApi adminApi() {
-        return GroupedOpenApi.builder()
-                .group("admin")
-                .addOperationCustomizer((operation, handlerMethod) ->
-                        operation.addParametersItem(globalHeaderParameter())
-                )
-                .pathsToMatch("/admin-api/**")
-                .build();
-    }
-
     /**
      * API 摘要信息
      */
@@ -99,33 +71,82 @@ public class YudaoSwaggerAutoConfiguration {
     /**
      * 安全模式，这里配置通过请求头 Authorization 传递 token 参数
      */
-    private Map<String, SecurityScheme> securityScheme() {
-        Map<String, SecurityScheme> map = new HashMap<>();
+    private Map<String, SecurityScheme> buildSecuritySchemes() {
+        Map<String, SecurityScheme> securitySchemes = new HashMap<>();
         SecurityScheme securityScheme = new SecurityScheme()
-                //类型
-                .type(SecurityScheme.Type.APIKEY)
-                //请求头的name
-                .name(HttpHeaders.AUTHORIZATION)
-                //token所在未知
-                .in(SecurityScheme.In.HEADER);
-        map.put(HttpHeaders.AUTHORIZATION, securityScheme);
-        return map;
+                .type(SecurityScheme.Type.APIKEY) // 类型
+                .name(HttpHeaders.AUTHORIZATION) // 请求头的 name
+                .in(SecurityScheme.In.HEADER); // token 所在位置
+        securitySchemes.put(HttpHeaders.AUTHORIZATION, securityScheme);
+        return securitySchemes;
     }
 
     /**
-     * globalHeaderParameter
+     * 自定义 OpenAPI 处理器
+     */
+    @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);
+    }
+
+    // ========== 分组 OpenAPI 配置 ==========
+
+    /**
+     * 所有模块的 API 分组
+     */
+    @Bean
+    public GroupedOpenApi allGroupedOpenApi() {
+        return buildGroupedOpenApi("all", "");
+    }
+
+    public static GroupedOpenApi buildGroupedOpenApi(String group) {
+        return buildGroupedOpenApi(group, group);
+    }
+
+    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();
+    }
+
+    /**
+     * 构建 Tenant 租户编号请求头参数
+     *
      * @return 多租户参数
      */
-    private static Parameter globalHeaderParameter() {
+    private static Parameter buildTenantHeaderParameter() {
         return new Parameter()
-                .name(HEADER_TENANT_ID)
-                .description("租户编号")
-                .in(String.valueOf(SecurityScheme.In.HEADER))
-                .schema(new IntegerSchema()
-                        ._default(1L)
-                        .name(HEADER_TENANT_ID)
-                        .description("租户编号")
-                );
+                .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
     }
 
 }