如何在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 上的文档，但没有找到合适的例子......谢谢！

- Fel

Answer 1

使用@ArraySchema替代普通的@Schema来为数组类型定义输入或输出数据。

- y_ug

---

我看到了@ArraySchema注释，但是我误解了文档，认为它不是我所需要的...这是我的错误。现在使用这个注释：@ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = LocationResponse.class))), description = "Get location information")，它可以工作了。谢谢！ - Fel

完美的答案。相关问题：泛型通常如何工作？例如 PageDto<ItemDto>？目前我只能提供 PageDto.class。是否有一种方法可以向 Swagger 提供类型信息？谢谢！ - judos

Answer 2

对于PageDto<T>，我们可以简单地创建一个扩展PageDto<T>的ResponseDto，并将其用作Swagger中的： @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = ResponseDto.class))), description = "获取位置信息"),。谢谢

- Rohit Rathour

---

作为一种解决方法，我接受了这个。但是我认为应该有一种方法可以在不创建更多类的情况下使文档正确理解代码。我打开了一个工单来进一步调查此问题：https://github.com/swagger-api/swagger-core/issues/3851 - judos

Answer 3

代码应该看起来像这样！！

@ApiResponses(value = {
            @ApiResponse(responseCode = "200",
                    description = "Successful operation",
                    content = @Content(mediaType = "application/json",
                    array = @ArraySchema( schema = @Schema(implementation = LocationResponse.class))))})

- Jay Yadav