Spring: openAPI: Document array or list response

Using @ArraySchema annotation, we can document array responses.

 

Example

@Operation(summary = "Create new Employee", responses = {
            @ApiResponse(responseCode = "200", description = "OK", content = {
                    @Content(
                        mediaType = "application/json",
                        array = @ArraySchema(schema = @Schema(implementation = EmployeeCreateRequestDto.class)),
                        examples = {
                            @ExampleObject(name = "Example 1", summary = "Summary 1", description = "sample payload", 
                                value = "[{\"firstName\":\"Ram\",\"lastName\":\"Gurram\"},{\"firstName\":\"Krishna\",\"lastName\":\"N\"}]")
                        }
                    )
                })
            })
@PostMapping
public ResponseEntity<List<EmployeeCreateRequestDto>> createEmployee(
                @RequestBody(description = "Create new user", required = true, 
                content = @Content(mediaType = "application/json",
                        array = @ArraySchema(schema = @Schema(implementation = EmployeeCreateRequestDto.class)),
                        examples = {
                    @ExampleObject(name = "Example 1", summary = "Summary 1", description = "Some desc", 
                        value = "[{\"firstName\":\"Ram\",\"lastName\":\"Gurram\"},{\"firstName\":\"Krishna\",\"lastName\":\"N\"}]")
                }))
                @org.springframework.web.bind.annotation.RequestBody List<EmployeeCreateRequestDto> dtos) {

        return new ResponseEntity<>(dtos, HttpStatus.CREATED);

}

 

Above snippet generates below swagger documentation.

 

Follow below steps to build complete working application.

 

Step 1: Create new maven project ‘openapi-document-array-response’.

 

Step 2: Update pom.xml with maven dependencies.

 

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.sample.app</groupId>
    <artifactId>openapi-document-array-response</artifactId>
    <version>1</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.6.4</version>
    </parent>


    <properties>
        <java.version>1.8</java.version>
        <maven.compiler.source>${java.version}</maven.compiler.source>
        <maven.compiler.target>${java.version}</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.report.outputEncoding>UTF-8</project.report.outputEncoding>
    </properties>
    
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>


        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.6.6</version>
        </dependency>


    </dependencies>
</project>

 

Step 3: Define UserController class.

 

UserController.java

package com.sample.app.controller;

import java.util.List;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.CrossOrigin;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.ArraySchema;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.ExampleObject;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.parameters.RequestBody;
import io.swagger.v3.oas.annotations.responses.ApiResponse;

@RestController
@RequestMapping(value = "/api/v1/users")
@CrossOrigin("*")
public class UserController {

    @Operation(summary = "Create new Employee", responses = {
            @ApiResponse(responseCode = "200", description = "OK", content = {
                    @Content(
                        mediaType = "application/json",
                        array = @ArraySchema(schema = @Schema(implementation = EmployeeCreateRequestDto.class)),
                        examples = {
                            @ExampleObject(name = "Example 1", summary = "Summary 1", description = "Some desc", 
                                value = "[{\"firstName\":\"Ram\",\"lastName\":\"Gurram\"},{\"firstName\":\"Krishna\",\"lastName\":\"N\"}]")
                        }
                    )
                })
            })
    @PostMapping
    public ResponseEntity<List<EmployeeCreateRequestDto>> createEmployee(
            @RequestBody(description = "Create new user", required = true, 
            content = @Content(mediaType = "application/json",
                array = @ArraySchema(schema = @Schema(implementation = EmployeeCreateRequestDto.class)),
                examples = {
                        @ExampleObject(name = "Example 1", summary = "Summary 1", description = "sample payload", 
                            value = "[{\"firstName\":\"Ram\",\"lastName\":\"Gurram\"},{\"firstName\":\"Krishna\",\"lastName\":\"N\"}]")
                    }))
            @org.springframework.web.bind.annotation.RequestBody List<EmployeeCreateRequestDto> dtos) {

        return new ResponseEntity<>(dtos, HttpStatus.CREATED);

    }

    private static class EmployeeCreateRequestDto {
        private String firstName;
        private String lastName;

        public String getFirstName() {
            return firstName;
        }

        public void setFirstName(String firstName) {
            this.firstName = firstName;
        }

        public String getLastName() {
            return lastName;
        }

        public void setLastName(String lastName) {
            this.lastName = lastName;
        }

    }

}

 

Step 4: Define main application class.

 

App.java

package com.sample.app;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class App {
    public static void main(String[] args) {

        SpringApplication.run(App.class, args);

    }
}

 

Total project structure looks like below.

 

Run App.java.

 

Open the url ‘http://localhost:8080/swagger-ui/index.html’ to experiment with swagger documentation.

 

You can download the complete working application from this link.

  

Previous                                                    Next                                                    Home