Using 'io.swagger.v3.oas.annotations.parameters.RequestBody' annotation, we can document the request payload.
Example
@Operation(summary = "Create new Employee")
@PostMapping
public ResponseEntity<EmployeeCreateRequestDto> createEmployee(
@RequestBody(description = "Create new user", required = true,
content = @Content(schema = @Schema(implementation = EmployeeCreateRequestDto.class)))
@org.springframework.web.bind.annotation.RequestBody EmployeeCreateRequestDto dto) {
return new ResponseEntity<>(dto, HttpStatus.CREATED);
}
Above snippet generates below documentation.
Find the below working application.
Step 1: Create new maven project ‘openapi-document-request-payload’.
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-request-payload</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 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.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.parameters.RequestBody;
@RestController
@RequestMapping(value = "/api/v1/users")
@CrossOrigin("*")
public class UserController {
@Operation(summary = "Create new Employee")
@PostMapping
public ResponseEntity<EmployeeCreateRequestDto> createEmployee(
@RequestBody(description = "Create new user", required = true,
content = @Content(schema = @Schema(implementation = EmployeeCreateRequestDto.class)))
@org.springframework.web.bind.annotation.RequestBody EmployeeCreateRequestDto dto) {
return new ResponseEntity<>(dto, 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 the swagger ui.
You can download complete working application from this link.
Previous Next Home
No comments:
Post a Comment