Springfox 3（Swagger）如何为对象列表类型的RequestBody生成有效接口文档？

我之前也碰到过Springfox Swagger处理列表类型RequestBody的坑，确实挺让人头疼的！结合你的问题和实际使用经验，给你梳理下可能的解决思路，以及为什么转用SpringDoc是个好选择：

Springfox下的临时修复方案 #

如果还没完全切换到SpringDoc，可以试试这几个办法修正文档生成问题：

• 修正HTTP方法与注解的搭配：你代码里用了@GetMapping却搭配@RequestBody，这其实不符合HTTP规范——GET请求通常不会携带请求体，Springfox对这种非常规用法的支持本来就有问题。如果确实需要在请求体里传列表，建议改成@PostMapping或者@PutMapping，这大概率能让Swagger正确识别参数类型。
• 显式指定Schema类型：在@Parameter注解里手动指定schema，强制Swagger识别为数组类型：

  @PostMapping('foos')
  public ResponseEntity updateFoo(@RequestBody @Parameter(schema = @Schema(type = "array", implementation = Foo.class)) List<Foo> foos) {
      // do stuff
  }
  

• 封装列表到DTO对象：创建一个专门的DTO类来包裹列表，比如：

  public class FooListRequest {
      private List<Foo> foos;
      // getter & setter
  }
  

  然后接口里用这个DTO作为@RequestBody的参数，Springfox对这种封装后的对象识别会更准确。

为什么转用SpringDoc更省心 #

你们项目决定转用SpringDoc真的是个明智的选择！SpringDoc基于OpenAPI 3规范开发，对Spring Boot新版本的兼容性更好，处理这种列表类型的参数完全不需要额外的hack——直接写@RequestBody List<Foo> foos，就能自动生成正确的数组类型Swagger文档，完美契合你期望的结构。而且SpringDoc的社区维护更活跃，后续遇到问题也更容易找到解决方案。

内容的提问来源于stack exchange，提问作者Sonja