暂存提交

common-openapi/AGENTS.md

@@ -12,9 +12,11 @@
 | 自动配置 | `src/main/java/com/baiyue/common/openapi/BaiyueOpenApiAutoConfiguration.java` |
 | `baiyue.openapi` 配置项 | `src/main/java/com/baiyue/common/openapi/OpenApiProperties.java` |
 | 自动配置注册 | `src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` |
+| 长整型 OpenAPI 字符串契约 | `src/main/java/com/baiyue/common/openapi/BaiyueOpenApiAutoConfiguration.java` |
 
 ## 修改与验证
 
 - 调整分组、标题或安全方案时检查所有 MVC 服务的 Swagger 输出；Gateway 的 WebFlux 聚合配置在 `gateway/`。
 - 配置项变化优先保持旧键兼容，并同步 Nacos 模板。
 - 从父目录运行 `mvn -pl common-openapi -am test`。
+- 所有 Java `Long/long` 在 OpenAPI 中统一声明为字符串，与 HTTP JSON 序列化保持一致。

common-openapi/pom.xml

@@ -10,5 +10,6 @@
     <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>
+        <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
     </dependencies>
 </project>

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

@@ -1,5 +1,7 @@
 package com.baiyue.common.openapi;
 
+import com.fasterxml.jackson.databind.type.TypeFactory;
+import io.swagger.v3.core.converter.ModelConverter;
 import io.swagger.v3.oas.models.Components;
 import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.info.Info;
@@ -43,6 +45,22 @@ public class BaiyueOpenApiAutoConfiguration {
             .addParametersItem(header("X-Trace-Id", "Distributed trace ID / 分布式追踪 ID", false));
     }
 
+    /** 保证 OpenAPI 与运行时 JSON 一致：所有 Java 长整型均声明为字符串。 */
+    @Bean
+    ModelConverter longAsStringModelConverter() {
+        return (type, context, chain) -> {
+            if (type.getType() != null) {
+                Class<?> rawType = TypeFactory.defaultInstance().constructType(type.getType()).getRawClass();
+                if (rawType == Long.class || rawType == Long.TYPE) {
+                    return new io.swagger.v3.oas.models.media.StringSchema()
+                            .description("长整型以字符串传输，避免浏览器精度丢失")
+                            .example("190000000000000001");
+                }
+            }
+            return chain.hasNext() ? chain.next().resolve(type, context, chain) : null;
+        };
+    }
+
     @Bean
     GroupedOpenApi platformApi(OperationCustomizer tenantHeaderCustomizer) {
         return GroupedOpenApi.builder().group("platform")

common-openapi/src/test/java/com/baiyue/common/openapi/LongAsStringModelConverterTest.java

@@ -0,0 +1,29 @@
+package com.baiyue.common.openapi;
+
+import io.swagger.v3.core.converter.AnnotatedType;
+import io.swagger.v3.core.converter.ModelConverter;
+import io.swagger.v3.core.converter.ModelConverterContext;
+import io.swagger.v3.oas.models.media.Schema;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.Collections;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DisplayName("长整型标识 OpenAPI 序列化功能")
+class LongAsStringModelConverterTest {
+
+    @Test
+    void longShouldBeDocumentedAsString() {
+        ModelConverter converter = new BaiyueOpenApiAutoConfiguration().longAsStringModelConverter();
+
+        Schema<?> schema = converter.resolve(
+                new AnnotatedType(Long.class),
+                org.mockito.Mockito.mock(ModelConverterContext.class),
+                Collections.emptyIterator());
+
+        assertThat(schema.getType()).isEqualTo("string");
+        assertThat(schema.getExample()).isEqualTo("190000000000000001");
+    }
+}