通过为请求和响应分别定义专用 dto 类（如 fooreq/fooresp），可在 swagger 中精准控制字段展示：post /bar 仅显示 foo.id，而 foo 自身接口仍完整显示所有字段。
通过为请求和响应分别定义专用 dto 类（如 fooreq/fooresp），可在 swagger 中精准控制字段展示：post /bar 仅显示 foo.id，而 foo 自身接口仍完整显示所有字段。
在 Spring Boot 项目中集成 Swagger（如 Springdoc OpenAPI）时，常遇到同一业务实体在不同接口中需呈现不同字段可见性的需求。例如，Bar 资源创建（POST /bar）仅需接收 Foo 的 id 字段用于关联，但查询（GET /bar/{id}）返回时需包含 Foo 的全部字段（如 id 和 name）；与此同时，Foo 自身的 CRUD 接口（如 POST /foo）又必须接收并返回所有字段。若共用同一 Foo 类，Swagger 将统一渲染所有字段，无法满足这种“按接口定制”的文档需求。
解决方案：职责分离 —— 为请求与响应分别建模
核心原则是避免复用同一 DTO 类承载多种语义。应按数据流向与契约边界拆分类型：
// 请求专用：仅含必要字段（Swagger POST /bar 中只显示 id）
public class FooReq {
private String id;
// getter/setter...
}
// 响应专用：继承请求类，扩展读取字段（Swagger 中完整展示）
public class FooResp extends FooReq {
private String name;
// getter/setter...
}
// Bar 请求体：组合 FooReq
public class BarReq {
private String id;
private FooReq foo; // Swagger 仅渲染 foo.id
// getter/setter...
}
// Bar 响应体：组合 FooResp
public class BarResp {
private String id;
private FooResp foo; // Swagger 渲染 foo.id + foo.name
// getter/setter...
}控制器方法明确声明输入输出类型：
@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 = findBarById(id);
return ResponseEntity.ok(barResp);
}
}✅ 效果验证：Swagger UI 中，POST /bar 的 Request Body 示例与 Schema 仅显示 {"id":"string","foo":{"id":"string"}}；而 GET /bar/{id} 的 Response Schema 则显示 {"id":"string","foo":{"id":"string","name":"string"}}。POST /foo 接口则使用独立的 FooReq 或完整 Foo 类，完全不受影响。
注意事项：
- 避免过度继承：若 FooResp 与 FooReq 字段差异大，建议改为组合而非继承，提升可维护性；
- 使用 @Schema(hidden = true) 仅适用于全局隐藏，无法实现“同字段在不同接口中差异化展示”，故不推荐；
- 配合 Lombok 可减少样板代码：@Data + @NoArgsConstructor + @AllArgsConstructor；
- 若需进一步精简 Swagger 描述，可对字段添加 @Schema(description = "关联的 Foo 主键") 等注解。
该方案符合 RESTful 设计原则与契约优先（Contract-First）实践，既保证 API 文档准确性，又提升客户端开发体验——每个端点的请求/响应结构一目了然，无冗余干扰。
