How to specify a list using OpenAPI 3 Swagger annotations

Question

For my API I'm making a meta annotation for handling Pagable parameters and for it I need to annotate a list of strings as a parameter that will show up in Swagger UI.

import io.swagger.v3.oas.annotations.Parameter;

@Parameter(name = "sort", in = ParameterIn.QUERY, schema = @Schema(implementation = String.class, type = "query"))
public @interface PageableQueryParameters {}

In order to sort by multiple criteria in Spring's Pageable the sort parameter needs to be provided as a list of strings. Unfortunately I don't know how to declare the sort parameter as a list.

How can I document a list of strings using Swagger's OpenAPI 3 annotations?

mcarlin · Accepted Answer · 2020-11-30 18:44:59Z

1

If I'm understanding you correctly, to indicate that the "sort" parameter is a list, you need to use the parameters array like the following:

schema = @Schema(implementation = String.class, type = "query"

should be changed to

array = @ArraySchema(implementation = String.class)

edited Nov 30, 2020 at 18:44

answered Nov 30, 2020 at 12:57

mcarlin

1,6371 gold badge12 silver badges16 bronze badges

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

2 Comments

Michael Dz Over a year ago

Unfortunately Swagger UI still shows sort as a single parameter.

Spaik Saucus Over a year ago

parameters = { @Parameter(in = ParameterIn.QUERY, required = false, name = "sort", description = "Sorting criteria in the format: property(,asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", example = "sort=customerId,desc&sort=id,desc", array = @ArraySchema( schema = @Schema(type = "string"))) }

Brian Boothe · Accepted Answer · 2023-09-08 09:49:08Z

1

You should use this:

array = @ArraySchema(schema = @Schema(implementation = String.class))

edited Sep 8, 2023 at 9:49

answered Aug 18, 2023 at 9:42

Brian Boothe

112 bronze badges

1 Comment

inetphantom Sep 23 at 13:26

in 2025 this should be the accepted answer

Collectives™ on Stack Overflow

How to specify a list using OpenAPI 3 Swagger annotations

2 Answers 2

2 Comments

1 Comment

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

2 Comments

1 Comment

Your Answer

Sign up or log in

Post as a guest

Related