Swagger UI OpenAPI 3, query parameters displayed as an object instead of value-changeable fields

Question

Previously in SpringBoot v2.5.7, I had this Spring REST controller method. It had a TestCriteria type DTO, as the path param.

@GetMapping(path = "/test")
public void test(TestCriteria testCriteria) {

}

And the TestCriteria class was like this. (Language is an enum that can take either EN or FR).

public class TestCriteria {
    @ApiModelProperty(allowEmptyValue = true)
    List<Language> langauges;
    
}

I used Springfox Swagger (springfox-boot-starter v3) and the Swagger UI looked like this:

But later I had to upgrade SpringBoot to v3, and use Springdoc and OpenAPI v3 for Swagger. Now the TestCriteria class looks like this:

public class TestCriteria {

    @Schema(type="array")
    @Parameter(allowEmptyValue = true)
    List<Langauge> languages;

}

Now Swagger UI does not display languages as a value-selectable field, but as an object.

I compared the generated OpenAPI definition as well and found,

previous API docs -

  parameters:
    - name: languages
      in: query
      required: false
      type: array
      items:
        type: string
        enum:
          - EN
          - FR
      collectionFormat: multi
      enum:
        - EN
        - FR

new API doc -

parameters:
  - name: testCriteria
    in: query
    required: true
    schema:
      $ref: '#/components/schemas/TestCriteria'

Is there a way I can provide the previous Swagger UI view, where the user can select a value from the enum list, rather than getting user's input via an object representation?

laffuste · Accepted Answer · 2024-09-11 03:24:49Z

8

Finally got the Swagger UI displayed as expected.

In the controller method argument, we need to add the @ParameterObject annotation:

@GetMapping(path = "/test")
public void test(@ParameterObject TestCriteria testCriteria) {

}

Or, alternatively, annotate the param class:

@ParameterObject
public class TestCriteria {...}

This is explained in the Springfox to Springdoc migration doc:

If you’re using an object to capture multiple request query params, annotate that method argument with @ParameterObject.

edited Sep 11, 2024 at 3:24

laffuste

17.2k8 gold badges90 silver badges94 bronze badges

answered Feb 2, 2023 at 1:55

Ishara M

2971 gold badge5 silver badges12 bronze badges

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

Collectives™ on Stack Overflow

Swagger UI OpenAPI 3, query parameters displayed as an object instead of value-changeable fields

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related