SpringDoc OpenAPI中多响应状态码处理的注意事项

在使用SpringDoc OpenAPI为Spring Boot应用生成API文档时，开发者可能会遇到一个关于@ResponseStatus注解的特殊情况。本文将深入分析这个问题及其解决方案。

问题背景

在Spring Boot应用中，我们经常会使用@ResponseStatus注解来指定控制器方法的HTTP响应状态码。当同一个路径下有多个方法，且这些方法都使用了相同的@ResponseStatus值时，SpringDoc OpenAPI的文档生成可能会出现预期之外的行为。

问题复现

考虑以下控制器示例：

@RestController
public class MyController {

  @PostMapping(path = "{id}", 
               consumes = MediaType.APPLICATION_JSON_VALUE,
               produces = {"application/json", "application/x.company+json"})
  @ResponseStatus(HttpStatus.CREATED)
  public Flux<String> asString() {
    // 方法实现
  }

  @PostMapping(path = "{id}", 
               consumes = MediaType.APPLICATION_JSON_VALUE,
               produces = {"application/x.company.group+json"})
  @ResponseStatus(HttpStatus.CREATED)
  public Flux<Integer> asInteger() {
    // 方法实现
  }
}

在这个例子中，两个方法都映射到相同的路径/{id}，但处理不同的内容类型(produces)。理想情况下，生成的OpenAPI文档应该显示所有支持的内容类型。然而实际上，只有application/x.company.group+json会出现在文档中。

技术分析

这个问题源于SpringDoc OpenAPI内部处理@ResponseStatus注解的方式。在GenericResponseService类中，当检测到方法上有@ResponseStatus注解时，它会检查是否已经为该状态码创建了响应。如果已经存在相同状态码的响应，它就不会添加新的响应定义。

这种行为导致了当多个方法使用相同的@ResponseStatus值时，只有第一个被处理的方法的内容类型会被包含在文档中。

解决方案

针对这个问题，可以修改GenericResponseService的逻辑，使其在遇到相同状态码时，不是简单地跳过，而是将新的内容类型合并到现有的响应定义中。具体修改如下：

if (Objects.nonNull(httpCode)) {
    if (!apiResponsesOp.containsKey(httpCode) && !apiResponsesOp.containsKey(ApiResponses.DEFAULT)) {
        buildApiResponses(components, methodParameter, apiResponsesOp, methodAttributes, httpCode, new ApiResponse(), false);
    } else {
        buildApiResponses(components, methodParameter, apiResponsesOp, methodAttributes, httpCode, apiResponsesOp.get(httpCode), false);
    }
}

这个修改确保当遇到相同状态码时，新的内容类型会被添加到现有的响应定义中，而不是被忽略。

最佳实践

为了避免这类问题，开发者可以考虑以下实践：

1. 对于相同路径的不同内容类型处理，考虑使用单一方法并通过内容协商来处理不同的返回类型
2. 如果必须使用多个方法，确保每个方法有独特的状态码，或者手动合并响应定义
3. 定期检查生成的OpenAPI文档，确保它准确反映了API的实际行为

总结

SpringDoc OpenAPI是一个强大的工具，可以自动从Spring Boot应用中生成API文档。然而，在某些特定场景下，如多个方法使用相同的@ResponseStatus值时，开发者需要注意其默认行为可能不符合预期。理解这些内部机制有助于开发者更好地控制生成的文档内容，确保API文档的准确性和完整性。