暂存提交

2026-07-30 18:01:36 +08:00
commit 2f4e159356
368 changed files with 20370 additions and 0 deletions
@@ -0,0 +1,67 @@
+package com.baiyue.common.openapi;
+
+import io.swagger.v3.oas.models.Components;
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+import io.swagger.v3.oas.models.parameters.HeaderParameter;
+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.customizers.OperationCustomizer;
+import org.springdoc.core.models.GroupedOpenApi;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+
+/**
+ * OpenAPI 公共自动配置，根据服务配置生成统一的接口文档元数据和 JWT 安全方案。
+ */
+@AutoConfiguration
+@EnableConfigurationProperties(OpenApiProperties.class)
+@ConditionalOnProperty(prefix = "baiyue.openapi", name = "enabled", havingValue = "true", matchIfMissing = true)
+public class BaiyueOpenApiAutoConfiguration {
+    public static final String BEARER = "bearerAuth";
+
+    @Bean
+    OpenAPI baiyueOpenApi(OpenApiProperties p) {
+        return new OpenAPI()
+            .info(new Info().title(p.getTitle()).description(p.getDescription()).version(p.getVersion()))
+            .components(new Components().addSecuritySchemes(BEARER,
+                new SecurityScheme().name(BEARER).type(SecurityScheme.Type.HTTP)
+                    .scheme("bearer").bearerFormat("JWT")))
+            .addSecurityItem(new SecurityRequirement().addList(BEARER));
+    }
+
+    @Bean
+    OperationCustomizer tenantHeaderCustomizer() {
+        return (operation, method) -> operation
+            .addParametersItem(header("X-Tenant-Id", "Current tenant ID / 当前租户 ID", false))
+            .addParametersItem(header("X-Operator-Tenant-Id", "Operator tenant ID / 运营方租户 ID", false))
+            .addParametersItem(header("X-App-Code", "Application code / 应用编码", false))
+            .addParametersItem(header("X-Request-Id", "Request correlation ID / 请求关联 ID", false))
+            .addParametersItem(header("X-Trace-Id", "Distributed trace ID / 分布式追踪 ID", false));
+    }
+
+    @Bean
+    GroupedOpenApi platformApi(OperationCustomizer tenantHeaderCustomizer) {
+        return GroupedOpenApi.builder().group("platform")
+            .displayName("Platform APIs / 平台端接口")
+            .pathsToMatch("/api/platform/**", "/api/auth/**", "/api/iam/platform/**")
+            .addOperationCustomizer(tenantHeaderCustomizer).build();
+    }
+
+    @Bean
+    GroupedOpenApi merchantApi(OperationCustomizer tenantHeaderCustomizer) {
+        return GroupedOpenApi.builder().group("merchant")
+            .displayName("Merchant APIs / 商户端接口")
+            .pathsToMatch("/api/merchant/**", "/api/orders/**", "/api/warehouse/**",
+                "/api/firstleg/**", "/api/lastleg/**")
+            .addOperationCustomizer(tenantHeaderCustomizer).build();
+    }
+
+    private Parameter header(String name, String description, boolean required) {
+        return new HeaderParameter().name(name).description(description).required(required)
+            .schema(new io.swagger.v3.oas.models.media.StringSchema());
+    }
+}