通过为请求和响应分别定义专用 DTO 类（如 FooReq/FooResp），可在 Swagger 文档中精准控制字段展示：POST /bar 仅显示 Foo 的 id 字段，而 GET 响应及独立的 Foo 接口仍完整呈现所有字段。
通过为不同请求/响应场景分别定义专用 dto 类（如 fooreq/fooresp），可在 swagger 文档中精准控制字段展示：post /bar 仅显示 foo 的 id 字段，而 get 响应及独立的 foo 接口仍完整呈现所有字段。
在 Spring Boot + Springdoc OpenAPI（或旧版 Swagger）实践中，一个常见痛点是：同一业务实体（如 Foo）在不同接口中承担不同职责——作为嵌套请求体时只需部分字段（如仅 id），作为独立资源或响应体时却需全部字段（如 id + name）。若共用同一 DTO，Swagger 会统一渲染所有字段，导致文档失真、前端困惑，甚至暴露不应由客户端填写的字段。
推荐解法：职责分离，DTO 分层建模
不建议使用 @Schema(hidden = true) 或 @JsonIgnore 等注解强行隐藏字段——它们作用于类级别，无法实现“同一字段在不同上下文中差异化展示”。正确做法是为请求（Request）与响应（Response）分别设计语义清晰的 DTO：
// 请求专用：仅含客户端需提交的字段
public class FooReq {
private String id;
// 注意：不包含 name，POST /bar 时无需提供
}
// 响应专用：继承请求结构，扩展服务端返回字段
public class FooResp extends FooReq {
private String name; // 服务端生成/查询所得，仅出现在响应中
}
// 对应 Bar 的请求体（嵌套 FooReq）
public class BarReq {
private String id;
private FooReq foo; // 关键：此处引用的是精简版
}
// 对应 Bar 的响应体（嵌套 FooResp）
public class BarResp {
private String id;
private FooResp foo; // 返回完整信息
}控制器方法明确声明输入输出类型，Springdoc 将据此生成精准文档：
@RestController
@RequestMapping("/api")
public class BarController {
@PostMapping("/bar")
public ResponseEntity<BarResp> postBar(@RequestBody BarReq barReq) {
// 处理逻辑：根据 barReq.foo.id 查找/关联 Foo 实体
BarResp response = buildBarResp(barReq);
return ResponseEntity.ok(response);
}
@GetMapping("/bar/{id}")
public ResponseEntity<BarResp> getBar(@PathVariable String id) {
BarResp barResp = fetchBarById(id);
return ResponseEntity.ok(barResp);
}
}✅ 效果验证：
- Swagger UI 中 /bar POST 的 Request body 示例与模型仅显示 id 和 foo.id；
- /bar GET 及 /foo POST/GET 接口仍正常显示 Foo 全量字段（因它们各自使用 FooReq 或 FooResp）；
- 编译期类型安全，避免运行时字段误用。
⚠️ 注意事项：
- 避免过度继承：若 FooResp 仅比 FooReq 多 1–2 个字段，继承合理；若差异大，建议组合优于继承；
- 映射逻辑需显式处理（如使用 MapStruct 或手动赋值），确保 BarReq → BarResp 转换时 FooReq 正确补全为 FooResp；
- 若项目已使用 Lombok，可为各 DTO 单独添加 @Data 或 @Getter/@Setter，避免重复模板代码。
该模式不仅解决 Swagger 字段可见性问题，更符合 REST API 设计原则：请求体（Input）应最小化、响应体（Output）应最大化且自描述。长期看，它提升了 API 的可维护性与契约清晰度。
