How to annotate array of objects response in Swagger

Question

I have to debug a REST API Java project that has been developed using Swagger.I'm new to it, so I'm a little bit confused on how to do certain things. For example, here's one method:

@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 */ }

The @ApiResponse for the code 200 is not of type LocationResponse but of type ArrayList<LocationResponse>, as it can return more than one location. What would be the correct syntax for this change? I've been reading the documentation at https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations#operation-annotations but I couldn't find an appropriate example...

Thanks!

Answer 1

Use @ArraySchema instead of plain @Schema to define input or output data for array types.

Answer 2

For the PageDto<T> we can simply create ResponseDto which extends PageDto<T> and use it in swagger as : @ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = ResponseDto.class))), description = "Get location information"),. Thank You