Spring Boot3迁移：OpenAPI @Operation响应类能否简化配置？

问题背景 #

从Spring Boot 2迁移至Spring Boot 3时，需将Swagger 2注解替换为OpenAPI注解。原Swagger 2仅需一行即可指定接口描述和响应类：

@ApiOperation(value = "Create Employee", response = EmployeeResponse.class)

而对应的OpenAPI写法需要大量模板代码，显得冗余：

@Operation( summary = "Create Employee", 
   responses = { 
        @ApiResponse(responseCode = "200", description = "Success", 
            content = @Content(mediaType = MediaType.APPLICATION_JSON_VALUE, 
            schema = @Schema(implementation = EmployeeResponse.class)))
    }   
)

希望找到更简洁的方式，尽可能减少冗余代码，实现类似原Swagger 2仅指定类名的效果。

解决方案 #

1. 利用SpringDoc自动推导响应类型 #

Spring Boot 3默认集成SpringDoc作为OpenAPI实现，它能自动根据控制器方法的返回值类型生成响应文档，无需显式编写@ApiResponse：

如果方法直接返回EmployeeResponse：

@Operation(summary = "Create Employee")
@PostMapping("/employees")
public EmployeeResponse createEmployee(@RequestBody EmployeeRequest request) {
    // 业务逻辑实现
}

此时SpringDoc会自动识别：

• 200状态码的响应描述为"Success"
• 响应媒体类型为application/json
• 响应schema为EmployeeResponse.class
  完全等效于原Swagger 2的@ApiOperation写法。

如果方法返回ResponseEntity<EmployeeResponse>，SpringDoc同样能自动解析泛型中的响应类，无需额外配置。

2. 自定义组合注解封装模板代码 #

如果遇到无法自动推导的场景（比如需要自定义响应描述、指定非200状态码，或统一规范接口注解），可以自定义组合注解，把重复的模板代码封装起来：

固定响应类的组合注解

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Operation
@ApiResponse(
    responseCode = "200",
    description = "Success",
    content = @Content(
        mediaType = MediaType.APPLICATION_JSON_VALUE,
        schema = @Schema(implementation = EmployeeResponse.class)
    )
)
public @interface ApiCreateEmployee {
    String summary() default "Create Employee";
}

使用时只需一行：

@ApiCreateEmployee
@PostMapping("/employees")
public ResponseEntity<EmployeeResponse> createEmployee(@RequestBody EmployeeRequest request) {
    // 业务逻辑实现
}

支持动态响应类的组合注解

如果需要适配不同的响应类，可以将响应类作为注解参数：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Operation
@ApiResponse(
    responseCode = "200",
    description = "Success",
    content = @Content(
        mediaType = MediaType.APPLICATION_JSON_VALUE,
        schema = @Schema(implementation = "#{#responseClass}")
    )
)
public @interface ApiOperationV3 {
    String summary() default "";
    Class<?> responseClass();
}

使用时和原Swagger 2写法几乎一致：

@ApiOperationV3(summary = "Create Employee", responseClass = EmployeeResponse.class)
@PostMapping("/employees")
public ResponseEntity<EmployeeResponse> createEmployee(@RequestBody EmployeeRequest request) {
    // 业务逻辑实现
}

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