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!

y_ug · Accepted Answer · 2020-01-31 10:55:43Z

59

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

answered Jan 31, 2020 at 10:55

y_ug

1,1248 silver badges8 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

Fel Over a year ago

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!

judos Over a year ago

Perfect answer. Related question: How does it work with generics in general? e.g. PageDto<ItemDto> ? Currently I can only provide PageDto.class. Is there a a way to provide type information to swagger? Thanks!

solujic · Accepted Answer · 2023-12-07 18:03:51Z

13

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"),

edited Dec 7, 2023 at 18:03

solujic

1,0551 gold badge20 silver badges47 bronze badges

answered Mar 2, 2022 at 9:18

Rohit Rathour

1311 silver badge2 bronze badges

1 Comment

judos Over a year ago

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: github.com/swagger-api/swagger-core/issues/3851

solujic · Accepted Answer · 2023-12-07 09:04:52Z

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

Collectives™ on Stack Overflow

How to annotate array of objects response in Swagger

3 Answers 3

2 Comments

1 Comment

Comments

Linked

Hot Network Questions