暂存提交

common-openapi/pom.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>com.baiyue.firstleg</groupId><artifactId>baiyue-firstleg-platform</artifactId>
+        <version>1.0.0-SNAPSHOT</version><relativePath>../pom.xml</relativePath>
+    </parent>
+    <groupId>com.baiyue.shared</groupId>
+    <artifactId>baiyue-common-openapi</artifactId>
+    <dependencies>
+        <dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId></dependency>
+        <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId><optional>true</optional></dependency>
+    </dependencies>
+</project>

common-openapi/src/main/java/com/baiyue/common/openapi/BaiyueOpenApiAutoConfiguration.java

@@ -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());
+    }
+}

common-openapi/src/main/java/com/baiyue/common/openapi/OpenApiProperties.java

@@ -0,0 +1,28 @@
+package com.baiyue.common.openapi;
+
+import lombok.Getter;
+import lombok.Setter;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+
+/**
+ * OpenAPI 文档配置模型，定义文档开关、服务信息、联系人、许可证和服务器地址。
+ */
+@Getter
+@Setter
+@ConfigurationProperties("baiyue.openapi")
+public class OpenApiProperties {
+    private String title = "Baiyue Platform API / 柏悦平台接口";
+    private String description = "Logistics SaaS API / 物流 SaaS 接口";
+    private String version = "v1";
+    private boolean enabled = true;
+
+    
+    
+    
+    
+    
+    
+    
+    
+}

common-openapi/src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

@@ -0,0 +1 @@
+com.baiyue.common.openapi.BaiyueOpenApiAutoConfiguration