暂存提交

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