提交swagger 对象接口补充

2026-04-15 15:28:11 +08:00
parent 73a13fd16d
commit f6ba09521a
41 changed files with 674 additions and 139 deletions
--- a/README.md
+++ b/README.md
@@ -396,4 +396,6 @@ docker build -t label-backend:latest .
 - 固定结构请求体禁止继续使用匿名 `Map<String, Object>` 或 `Map<String, String>`，必须定义 DTO 并补齐 `@Schema` 字段说明
 - 固定结构响应应优先使用明确 DTO，或至少为 Swagger 暴露对象补齐字段级 `@Schema` 注解
 - 路径参数、查询参数、请求体、分页包装和通用返回体都必须维护可读的 OpenAPI 文档说明
+- 需要保持历史兼容的原始 JSON 字符串请求体可以继续使用 `String`，但必须在 Swagger `@RequestBody` 中说明完整 JSON body 的提交方式和兼容原因
+- 修改 Controller 参数、请求 DTO、响应 DTO 或对外实体后，必须运行 `mvn -Dtest=OpenApiAnnotationTest test`，确保 Swagger 参数名称、类型和含义没有回退
 - 目录、配置、打包方式变化后，README、设计文档和部署说明必须同步更新