如何在 Swagger 中注释对象数组

Question

我必须调试一个使用 Swagger 开发的 REST API Java 项目。我是新手，所以我对如何做某些事情有点困惑。例如，这是一种方法：

@GET
@Path("/location/name")
@Produces({MediaType.APPLICATION_JSON})
@Operation(
    summary = "Get location information",
    tags = {"Information"},
    responses = {
        @ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = LocationResponse.class)), description = "Get location information"),
        @ApiResponse(responseCode = "500", description = "Error: Internal Server Error")
    }
)
public Response searchLocationByName(
    @Parameter(description = "Location name", required = true) @DefaultValue("Barcelona") @QueryParam("name") String locationName
) { /* METHOD CODE */ }

在@ApiResponse为代码200是不是类型LocationResponse，但类型的ArrayList<LocationResponse>，因为它可以返回多个位置。此更改的正确语法是什么？我一直在https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations#operation-annotations阅读文档，但我找不到合适的例子.. .

谢谢！

Answer 1

使用@ArraySchema而不是普通@Schema来定义数组类型的输入或输出数据。

Answer 2

对于PageDto<T>我们可以简单地创建ResponseDto扩展PageDto<T>并在 swagger 中使用它，如下所示：

@ApiResponse(
  responseCode = "200",
  content = @Content(
  array = 
    @ArraySchema(
      schema = @Schema(implementation = ResponseDto.class))), 
      description = "Get location information"),