1.8 KiB
1.8 KiB
Common OpenAPI 模块指引
职责边界
- 为 Spring MVC 服务提供 SpringDoc/OpenAPI 自动配置和统一文档元数据。
- 不在这里维护具体业务接口契约；服务专属 OpenAPI 文件留在对应服务资源目录。
快速索引
| 功能 | 入口 |
|---|---|
| 自动配置 | 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 |
| PDA OpenAPI 分组 | src/main/java/com/baiyue/common/openapi/BaiyueOpenApiAutoConfiguration.java 的 pda GroupedOpenApi；固定匹配 /api/pda/**，合同测试 src/test/java/com/baiyue/common/openapi/PdaOpenApiGroupContractTest.java |
修改与验证
- 调整分组、标题或安全方案时检查所有 MVC 服务的 Swagger 输出；Gateway 的 WebFlux 聚合配置在
gateway/。 - PDA Controller 必须进入独立
pda分组；新增或改名/api/pda/**路径时同步检查分组合同和目标服务 OpenAPI，不得混入平台或商户分组。 - 普通业务成功和失败在 OpenAPI 中统一描述为 HTTP 200，并提示调用方检查 body
code；只为 Security、协议、基础设施、Warehouse 503、Audit 202 和 Event Bridge 内部鉴权等真实状态边界声明非 200 响应。 - 配置项变化直接同步代码、全部消费者和 Nacos 模板，当前开发阶段不保留旧配置键兼容。
- 从父目录运行
mvn -pl common-openapi -am test。 - 所有 Java
Long/long在 OpenAPI 中统一声明为字符串，与 HTTP JSON 序列化保持一致。