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!

score 38 · Accepted Answer · answered Jan 31 '20 at 10:55

38

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

answered Jan 31 '20 at 10:55

y_ug

904
6
8

5

I saw the `@ArraySchema` annotation but I misunderstood the documentation and I thought that it wasn't what I needed... my fault. Now it's working with this annotation: `@ApiResponse(responseCode = "200", content = @Content(array = @ArraySchema(schema = @Schema(implementation = LocationResponse.class))), description = "Get location information"),`. Thanks! – Fel Jan 31 '20 at 11:31
Perfect answer. Related question: How does it work with generics in general? e.g. PageDto ? Currently I can only provide PageDto.class. Is there a a way to provide type information to swagger? Thanks! – judos Jan 07 '21 at 13:25

score 7 · Answer 2 · edited Mar 07 '22 at 08:03

7

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

edited Mar 07 '22 at 08:03

Procrastinator

2,526
30
27
36

answered Mar 02 '22 at 09:18

Rohit Rathour

71
1
1

1

As a workaround I accept that. However I would assume there should be a way to do this without creating more classes just to make the documentation correctly understand the code. I opened a ticket to further investigate this: https://github.com/swagger-api/swagger-core/issues/3851 – judos Mar 11 '22 at 14:55

score 0 · Answer 3 · answered Jun 05 '23 at 13:48

Code should look like this !!

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

How to annotate array of objects response in Swagger

3 Answers3