java springdoc @ApiResponses 如何将列表定义为 return 对象使用

Question

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

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

控制器class（@RestController）有一个入口点（@GetMapping），这个入口点应该return一个对象列表：MyClass.java。我在方法上方添加了 Swagger 注释，以便通过 swagger UI 页面创建 API 文档。

swagger 文档应该指出 return 对象的类型是

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

java springdoc @ApiResponses 如何将列表定义为 return 对象使用

java springdoc @ApiResponses how to define a List as return object using

java

spring-boot

springdoc