Java（含JAX-RS、Spring）中替代ProducesResponseType的方案有哪些？

.NET Core（当前通常指.NET 8及更高版本）的ProducesResponseType注解可以明确声明REST端点的返回内容，对客户端自动生成工具帮助极大——不仅能生成响应类，还能生成完整的服务类（工具可识别每个HTTP状态码对应的处理逻辑）。它支持单独指定类型/状态码，或同时指定两者的组合：

[ProducesResponseType(typeof(DepartmentDto), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]

以下是Java生态中不同技术栈对应的替代方案：

1. Spring 框架 #

Spring中可通过**SpringDoc/Swagger的@ApiResponses+@ApiResponse**实现类似功能，配合Spring MVC/WebFlux的@Produces和ResponseEntity使用，能明确声明每个状态码对应的响应类型：

@PutMapping("/my-endpoint/{id}")
@Produces(MediaType.APPLICATION_JSON_VALUE)
@Consumes(MediaType.APPLICATION_JSON_VALUE)
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "成功返回部门信息", 
                 content = @Content(schema = @Schema(implementation = DepartmentDto.class))),
    @ApiResponse(responseCode = "404", description = "部门不存在")
})
public ResponseEntity<DepartmentDto> doTheThing(@PathVariable Long id, @RequestBody DepartmentDto dto) {
    // 业务逻辑实现
    return ResponseEntity.ok(dto);
}

如果不需要Swagger文档，ResponseEntity可在代码中直接指定状态码和返回对象，但要让客户端生成工具识别注解层面的声明，仍需依赖OpenAPI类注解。

2. JAX-RS（Jakarta RESTful Web Services） #

JAX-RS（如Jersey、RESTEasy等实现）同样依赖OpenAPI注解@ApiResponses和@ApiResponse来声明响应规则，可直接扩展你的遗留代码：

@PUT
@Path("/my-endpoint/{id}")
@Produces({MediaType.APPLICATION_JSON})
@Consumes(MediaType.APPLICATION_JSON)
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "操作成功", 
                 content = @Content(mediaType = MediaType.APPLICATION_JSON, 
                                   schema = @Schema(implementation = DepartmentDto.class))),
    @ApiResponse(responseCode = "404", description = "目标资源未找到")
})
public Response doTheThing(@PathParam("id") String id, DepartmentDto dto) {
    if (/* 资源不存在判断 */) {
        return Response.status(Response.Status.NOT_FOUND).build();
    }
    return Response.ok(dto).build();
}

原生JAX-RS的Response类可在代码中构建不同状态的响应，但注解层面的声明是客户端生成工具识别规则的关键。

3. 原生Java（无框架依赖） #

如果仅使用JDK自带的HttpServer等基础API，没有内置注解支持声明响应类型与状态码的组合，只能通过代码逻辑返回对应响应，且需要手动编写API文档供客户端工具解析。这种场景下更推荐使用JAX-RS规范的实现（如Jersey）来获得类似.NET的注解能力。

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