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

6

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

edited Dec 7, 2023 at 9:04

solujic

1,0551 gold badge20 silver badges47 bronze badges

answered Jun 5, 2023 at 13:48

Jay Yadav

6721 gold badge8 silver badges16 bronze badges

Collectives™ on Stack Overflow

How to annotate array of objects response in Swagger

3 Answers 3

2 Comments

1 Comment

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

2 Comments

1 Comment

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related