docs: add swagger dto annotation constraints

2026-04-15 14:18:32 +08:00
parent b65b1c6ee0
commit 00032dd491
2 changed files with 305 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -392,4 +392,8 @@ docker build -t label-backend:latest .
 - Service 统一放在 `service/`，不拆 `service/impl`
 - 业务规则优先放在 Service，Controller 只负责 HTTP 协议层
 - 新增接口需同步补齐 Swagger 注解与测试
+- 所有对外接口参数必须在 Swagger 中明确体现名称、类型和含义
+- 固定结构请求体禁止继续使用匿名 `Map<String, Object>` 或 `Map<String, String>`，必须定义 DTO 并补齐 `@Schema` 字段说明
+- 固定结构响应应优先使用明确 DTO，或至少为 Swagger 暴露对象补齐字段级 `@Schema` 注解
+- 路径参数、查询参数、请求体、分页包装和通用返回体都必须维护可读的 OpenAPI 文档说明
 - 目录、配置、打包方式变化后，README、设计文档和部署说明必须同步更新