java springdoc @ApiResponses 如何定义一个列表作为返回对象使用

Question

我正在使用具有以下依赖项的 SpringBoot

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

Controller 类(@RestController)有一个入口点(@GetMapping)，这个入口点应该返回一个对象列表:MyClass.java。我在方法上方添加了 Swagger 注释，以便通过 swagger UI 页面创建 API 文档。

swagger 文档应该指明返回对象是类型

List< MyClass>

但是我应该怎么做呢？如果我这样做

"@Schema(implementation = List< MyClass >.class)"

编译错误

Swagger 注释:

@Operation(....)
@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "successful operation",
                content = { @Content(mediaType = "application/json",
                        schema = @Schema(implementation = ????)) }),
        @ApiResponse(...),
        @ApiResponse(...)

@GetMapping(value = "/aaa", produces = MediaType.APPLICATION_JSON_VALUE)
public List<MyClass> getAaa(...)
{
    return ...
}

Answer 1

您需要使用 ArraySchema为此注释并将其分配给 array 属性而不是 @Content 注释的 schema 属性。您不需要仅指定 List.class 的类型参数 MyClass.class。

    @Operation(
            summary = "Get a list of users",
            description = "Get a list of users registered in the system",
            responses = {@ApiResponse(
                    responseCode = "200",
                    description = "The response for the user request",
                    content = {
                            @Content(
                                    mediaType = "application/json",
                                    array = @ArraySchema(schema = @Schema(implementation = User.class))
                            )
                    })
            }
    )
    @GET
    @SecurityRequirement(name = "JWT")
    @Path("/user")
    public List<User> getUsers() {
        return null;
    }