spring-bootswaggerswagger-2.0openapiapi-doc

Flattening RequestParam Object in OpenApi 3


I am migrating from swagger 2 to OpenApi 3.

Swagger 2 Sample Code


    @ApiOperation(value = "", nickname = "")
        @GetMapping
          public List<Employee> findEmployees(@Valid Dto dto) {
                return employeeService.findEmployees(dto);
                }

OpenApi 3 Code


    @Operation(summary = "")
        @GetMapping
          public List<Employee> findEmployees(@Valid Dto dto) {
                return employeeService.findEmployees(dto);
                }

DTO Class


    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    public class Dto {
        private String status;
        private String name;
        private String destination;
    }

There is a significant difference in generation of swagger-ui in both cases.

Swagger 2 shows the DTO object as flattened into individual query params :

Image Flattening of object as individual query parameters happens in Swagger 2 ui

while OpenApi 3 creates a JSON object:

Image Object doesnot flattens but creates a json object

I want to have the flattening behavior in OpenApi 3 like the way it used to be in Swagger 2. Is there any way to achieve the same in OPENAPI 3.


Solution

  • After some research i found that a new version of openapiui dependency has been released on 12th of april 2020 and it solves my issue in hand. From version 1.3.2 its available.

    <!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-ui</artifactId>
        <version>1.3.2</version>
    </dependency>
    

    The use of Annotation @ParameterObject before the query parameter object solves it.

    
       @Operation(summary = "")
            @GetMapping
              public List<Employee> findEmployees(**@ParameterObject** @Valid Dto dto) {
                    return employeeService.findEmployees(dto);
                    }