SpringFox Swagger2迁移至SpringDoc OpenAPI：@ApiOperation字段转换问题

1. 处理response字段（指定返回实体类型） #

SpringFox里用@ApiOperation(response = User.class)显式标记接口返回的实体类，在SpringDoc里有两种处理方式：

• 优先用方法返回值自动推导
  如果你的接口方法已经明确返回具体类型（比如public User getUserById(Long id)），SpringDoc会自动识别这个返回类型生成接口文档，不需要额外写注解声明，这也是最简洁的做法。
• 显式声明（针对泛型/模糊返回类型）
  如果方法返回ResponseEntity<?>这类模糊类型，就用@ApiResponse配合@Content、@Schema来指定：

  @Operation(summary = "获取单个用户信息")
  @ApiResponse(responseCode = "200", description = "查询成功",
               content = @Content(schema = @Schema(implementation = User.class)))
  public ResponseEntity<?> getUserById(Long id) {
      // 业务逻辑
  }
  

2. 处理responseContainer字段（指定集合容器） #

原来responseContainer = "List"用来标记返回集合类型，SpringDoc里不需要单独的容器字段，直接通过返回类型或注解指定即可：

• 返回明确的集合类型
  比如方法直接返回List<User>，SpringDoc会自动识别这是一个包含User元素的数组（OpenAPI规范里集合统一用array表示），无需额外配置：

  @Operation(summary = "获取用户列表")
  public List<User> listUsers() {
      // 业务逻辑
  }
  

• 模糊返回类型下声明集合
  如果返回ResponseEntity<?>，就在@ApiResponse的@Schema里指定type = "array"和元素类型：

  @Operation(summary = "获取用户列表")
  @ApiResponse(responseCode = "200", description = "查询成功",
               content = @Content(schema = @Schema(type = "array", implementation = User.class)))
  public ResponseEntity<?> listUsers() {
      // 业务逻辑
  }
  

  不管原来用的是List还是Set，OpenAPI规范里都统一用type = "array"来表示集合类型。

小提示 #

SpringDoc更偏向依赖Java代码本身的类型信息，尽量让接口方法返回明确的类型，能减少大量注解配置，也让代码更易读。

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