openapi - springdoc 多个 404 响应使用@ApiResponse(java 注释)

Question

如何使用 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 和以下部门:

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

Answer 1

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

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

每个 HTTP 代码，对于一个操作只能分配一个 ApiResponse 对象。
使用示例是一个很好的方法。
如果您的多个 404 响应具有不同的结构，您可以使用 oneof 如下:

@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;
    }

}
}