springdoc 使用@ApiResponse（java注释）的多个404响应

Posted 2023-03-10

【中文标题】springdoc 使用@ApiResponse（java注释）的多个404响应

【英文标题】：springdoc multiple 404 responses using @ApiResponse (java annotations)

【发布时间】：2020-11-25 20:57:08

【问题描述】：

如何使用 java 注释创建多个 404 响应（或更广泛地说，多个相同的 HTTP 代码响应）。

我试过了：

@ApiResponse(
    responseCode = "404",
    description = "Not Found 1"
)
@ApiResponse(
    responseCode = "404",
    description = "Not Found 2"
)

还有多个@Content:

@ApiResponse(
    responseCode = "404",
    content = 
        @Content(schema = @Schema(name = "404-1", description = "404-1")),
        @Content(schema = @Schema(name = "404-2", description = "404-2"))
    
)

我能得到类似于 multiple 的唯一方法是使用 @ExampleObject[]：

@ApiResponse(
    responseCode = "404",
    content = @Content(
        mediaType = "application/json",
        examples = 
            @ExampleObject(name = "404-1", description = "Not Found 1 desc"),
            @ExampleObject(name = "404-2", description = "Not Found 2 desc")
        
    )
)

这是不理想的，因为它需要人工交互才能查看所有这些，并且不想要；期望是：

- 200
- 404 Description 1
- 404 Description 2
- 404 Description 3

甚至更好：

- 200
- 404 Description 1
      Description 2
      Description 3

我正在使用 springdoc 和以下 dep：

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-ui</artifactId>
  <version>1.4.3</version>
</dependency>

【参考方案1】：

按照设计，而不是 springdoc，而是 OpenAPI-Specification，所有响应都存储在扩展 LinkedHashMap 的 ApiResponses 类型中。

https://github.com/OAI/OpenAPI-Specification/blob/3.0.1/versions/3.0.1.md#responsesObject

每个 HTTP 代码，对于一个操作只能分配一个 ApiResponse 对象。

使用示例是一个很好的方法。 如果您的多个 404 响应具有不同的结构，您可以使用如下之一：

@RestController
public class HelloController 

@GetMapping("/hello")
@ApiResponses(
        @ApiResponse(responseCode = "200"),
        @ApiResponse(description = "Not found", responseCode = "404",
                content = @Content(mediaType = "application/json", schema = @Schema(oneOf = 
                        Foo.class, Bar.class ))) )
String hello() 
    return null;



@Schema(description = "this is bar")
class Bar 
    private String bar;

    public String getBar() 
        return bar;
    

    public void setBar(String bar) 
        this.bar = bar;
    



@Schema(description = "this is foo")
class Foo 

    private String foo;

    public String getFoo() 
        return foo;
    

    public void setFoo(String foo) 
        this.foo = foo;
    

【讨论】：

这不符合我的业务需求，因为我可能有不同的原因同一实体会返回 404，但是，公平地说，我没有在我的问题中提到这一点。不过，这很可能是人们普遍想要的答案，我认为正确的答案超出了我的需求。有据可查的+1。谢谢！

【参考方案2】：

我通过在我想要换行的描述中添加一个 html <br/> 标记来解决我的问题：

@Operation(
   responses = 
      @ApiResponse(responseCode = "404", content = @Content,
         description = 
            "This is potential 404 #1 <br/>" +
            "This is potential 404 #2"
      )
   
)

或者，

您可以创建一个注释以使其更具可读性，例如@ApiResponse404 之类的内容，然后通过OperationCustomizer 将其添加到操作中：

@Override
public Operation customize(Operation operation, HandlerMethod handlerMethod) 
    ApiResponse404 notFounds = handlerMethod.getMethodAnnotation(ApiResponse404.class);
    if (notFounds != null)
        operation.getResponses()
                 .addApiResponse("404", new ApiResponse()
                                            .description(String.join("<br/>", notFounds.value()))
                                );
    return operation;

当然，您必须考虑@Content，您可以轻松地将其添加到注释中，但我的场景不需要它，我只需要描述。

然后在控制器中你可以使用注解：

@GetMapping("/helloworld")
@ApiResponse404("This is potential 404 #1", "This is potential 404 #2")
String getHelloWorld() 
    return "Hello. World.";