Spring boot REST API documentation

springboot-restful-webservices/pom.xml

@@ -67,6 +67,13 @@
 			<groupId>org.springframework.boot</groupId>
 			<artifactId>spring-boot-starter-actuator</artifactId>
 		</dependency>
+		<!-- https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-starter-webmvc-ui -->
+		<dependency>
+			<groupId>org.springdoc</groupId>
+			<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+			<version>2.0.4</version>
+		</dependency>
+
 	</dependencies>
 
 	<build>

springboot-restful-webservices/src/main/java/net/javaguides/springboot/SpringbootRestfulWebservicesApplication.java

@@ -1,11 +1,36 @@
 package net.javaguides.springboot;
 
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
+import io.swagger.v3.oas.annotations.OpenAPIDefinition;
+import io.swagger.v3.oas.annotations.info.Contact;
+import io.swagger.v3.oas.annotations.info.Info;
+import io.swagger.v3.oas.annotations.info.License;
 import org.modelmapper.ModelMapper;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.context.annotation.Bean;
 
 @SpringBootApplication
+@OpenAPIDefinition(
+		info = @Info(
+				title = "Spring Boot REST API Documentation",
+				description = "Spring Boot REST API Documentation",
+				version = "v1.0",
+				contact = @Contact(
+						name = "Ramesh",
+						email = "[email protected]",
+						url = "https://www.javaguides.net"
+				),
+				license = @License(
+						name = "Apache 2.0",
+						url = "https://www.javaguides.net/license"
+				)
+		),
+		externalDocs = @ExternalDocumentation(
+				description = "Spring Boot User Management Documentation",
+				url = "https://www.javaguides.net/user_management.html"
+		)
+)
 public class SpringbootRestfulWebservicesApplication {
 
 	@Bean

springboot-restful-webservices/src/main/java/net/javaguides/springboot/controller/UserController.java

@@ -1,5 +1,8 @@
 package net.javaguides.springboot.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.AllArgsConstructor;
 import net.javaguides.springboot.dto.UserDto;
@@ -15,20 +18,40 @@
 import java.time.LocalDateTime;
 import java.util.List;
 
+@Tag(
+        name = "CRUD REST APIs for User Resource",
+        description = "CRUD REST APIs - Create User, Update User, Get User, Get All Users, Delete User"
+)
 @RestController
 @AllArgsConstructor
 @RequestMapping("api/users")
 public class UserController {
 
     private UserService userService;
 
+    @Operation(
+            summary = "Create User REST API",
+            description = "Create User REST API is used to save user in a database"
+    )
+    @ApiResponse(
+            responseCode = "201",
+            description = "HTTP Status 201 CREATED"
+    )
     // build create User REST API
     @PostMapping
     public ResponseEntity<UserDto> createUser(@Valid @RequestBody UserDto user){
         UserDto savedUser = userService.createUser(user);
         return new ResponseEntity<>(savedUser, HttpStatus.CREATED);
     }
 
+    @Operation(
+            summary = "Get User By ID REST API",
+            description = "Get User By ID REST API is used to get a single user from the database"
+    )
+    @ApiResponse(
+            responseCode = "200",
+            description = "HTTP Status 200 SUCCESS"
+    )
     // build get user by id REST API
     // http://localhost:8080/api/users/1
     @GetMapping("{id}")
@@ -37,6 +60,14 @@ public ResponseEntity<UserDto> getUserById(@PathVariable("id") Long userId){
         return new ResponseEntity<>(user, HttpStatus.OK);
     }
 
+    @Operation(
+            summary = "Get All Users REST API",
+            description = "Get All Users REST API is used to get a all the users from the database"
+    )
+    @ApiResponse(
+            responseCode = "200",
+            description = "HTTP Status 200 SUCCESS"
+    )
     // Build Get All Users REST API
     // http://localhost:8080/api/users
     @GetMapping
@@ -45,6 +76,14 @@ public ResponseEntity<List<UserDto>> getAllUsers(){
         return new ResponseEntity<>(users, HttpStatus.OK);
     }
 
+    @Operation(
+            summary = "Update User REST API",
+            description = "Update User REST API is used to update a particular user in the database"
+    )
+    @ApiResponse(
+            responseCode = "200",
+            description = "HTTP Status 200 SUCCESS"
+    )
     // Build Update User REST API
     @PutMapping("{id}")
     // http://localhost:8080/api/users/1
@@ -55,6 +94,14 @@ public ResponseEntity<UserDto> updateUser(@PathVariable("id") Long userId,
         return new ResponseEntity<>(updatedUser, HttpStatus.OK);
     }
 
+    @Operation(
+            summary = "Delete User REST API",
+            description = "Delete User REST API is used to delete a particular user from the database"
+    )
+    @ApiResponse(
+            responseCode = "200",
+            description = "HTTP Status 200 SUCCESS"
+    )
     // Build Delete User REST API
     @DeleteMapping("{id}")
     public ResponseEntity<String> deleteUser(@PathVariable("id") Long userId){

springboot-restful-webservices/src/main/java/net/javaguides/springboot/dto/UserDto.java

@@ -1,12 +1,16 @@
 package net.javaguides.springboot.dto;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.Email;
 import jakarta.validation.constraints.NotEmpty;
 import lombok.AllArgsConstructor;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
 import lombok.Setter;
 
+@Schema(
+        description = "UserDto Model Information"
+)
 @Setter
 @Getter
 @NoArgsConstructor
@@ -15,14 +19,23 @@ public class UserDto {
 
     private Long id;
 
+    @Schema(
+            description = "User First Name"
+    )
     // User first name should not be null or empty
     @NotEmpty(message = "User first name should not be null or empty")
     private String firstName;
 
+    @Schema(
+            description = "User Last Name"
+    )
     // User last name should not be null or empty
     @NotEmpty(message = "User last name should not be null or empty")
     private String lastName;
 
+    @Schema(
+            description = "User Email Address"
+    )
     // User email should not be null or empty
     // Email address should be valid
     @NotEmpty(message = "User email should not be null or empty")