springdoc rest api documentation

Author: Ramesh Fadatare

pom.xml

@@ -82,6 +82,12 @@
 			<version>0.11.5</version>
 			<scope>runtime</scope>
 		</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>

src/main/java/com/springboot/blog/config/SecurityConfig.java

@@ -2,6 +2,8 @@
 
 import com.springboot.blog.security.JwtAuthenticationEntryPoint;
 import com.springboot.blog.security.JwtAuthenticationFilter;
+import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
+import io.swagger.v3.oas.annotations.security.SecurityScheme;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.http.HttpMethod;
@@ -22,6 +24,12 @@
 
 @Configuration
 @EnableMethodSecurity
+@SecurityScheme(
+        name = "Bear Authentication",
+        type = SecuritySchemeType.HTTP,
+        bearerFormat = "JWT",
+        scheme = "bearer"
+)
 public class SecurityConfig {
 
     private UserDetailsService userDetailsService;
@@ -57,6 +65,8 @@ SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
                         authorize.requestMatchers(HttpMethod.GET, "/api/**").permitAll()
                                 //.requestMatchers(HttpMethod.GET, "/api/categories/**").permitAll()
                                 .requestMatchers("/api/auth/**").permitAll()
+                                .requestMatchers("/swagger-ui/**").permitAll()
+                                .requestMatchers("/v3/api-docs/**").permitAll()
                                 .anyRequest().authenticated()
 
                 ).exceptionHandling( exception -> exception

src/main/java/com/springboot/blog/controller/PostController.java

@@ -4,6 +4,10 @@
 import com.springboot.blog.payload.PostResponse;
 import com.springboot.blog.service.PostService;
 import com.springboot.blog.utils.AppConstants;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.access.prepost.PreAuthorize;
@@ -13,7 +17,10 @@
 import java.util.List;
 
 @RestController
-@RequestMapping()
+@RequestMapping("/api/posts")
+@Tag(
+        name = "CRUD REST APIs for Post Resource"
+)
 public class PostController {
 
     private PostService postService;
@@ -22,15 +29,34 @@ public PostController(PostService postService) {
         this.postService = postService;
     }
 
+    @Operation(
+            summary = "Create Post REST API",
+            description = "Create Post REST API is used to save post into database"
+    )
+    @ApiResponse(
+            responseCode = "201",
+            description = "Http Status 201 CREATED"
+    )
+    @SecurityRequirement(
+            name = "Bear Authentication"
+    )
     // create blog post rest api
     @PreAuthorize("hasRole('ADMIN')")
-    @PostMapping("/api/v1/posts")
+    @PostMapping
     public ResponseEntity<PostDto> createPost(@Valid @RequestBody PostDto postDto){
         return new ResponseEntity<>(postService.createPost(postDto), HttpStatus.CREATED);
     }
 
+    @Operation(
+            summary = "Get All Posts REST API",
+            description = "Get All Posts REST API is used to fetch all the posts from the database"
+    )
+    @ApiResponse(
+            responseCode = "200",
+            description = "Http Status 200 SUCCESS"
+    )
     // get all posts rest api
-    @GetMapping("/api/v1/posts")
+    @GetMapping
     public PostResponse getAllPosts(
             @RequestParam(value = "pageNo", defaultValue = AppConstants.DEFAULT_PAGE_NUMBER, required = false) int pageNo,
             @RequestParam(value = "pageSize", defaultValue = AppConstants.DEFAULT_PAGE_SIZE, required = false) int pageSize,
@@ -40,25 +66,55 @@ public PostResponse getAllPosts(
         return postService.getAllPosts(pageNo, pageSize, sortBy, sortDir);
     }
 
+    @Operation(
+            summary = "Get Post By Id REST API",
+            description = "Get Post By Id REST API is used to get single post from the database"
+    )
+    @ApiResponse(
+            responseCode = "200",
+            description = "Http Status 200 SUCCESS"
+    )
     // get post by id
-    @GetMapping(value = "/api/v1/posts/{id}")
+    @GetMapping("/{id}")
     public ResponseEntity<PostDto> getPostById(@PathVariable(name = "id") long id){
         return ResponseEntity.ok(postService.getPostById(id));
     }
 
+    @Operation(
+            summary = "update Post REST API",
+            description = "Update Post REST API is used to update a particular post in the database"
+    )
+    @ApiResponse(
+            responseCode = "200",
+            description = "Http Status 200 SUCCESS"
+    )
+    @SecurityRequirement(
+            name = "Bear Authentication"
+    )
     // update post by id rest api
     @PreAuthorize("hasRole('ADMIN')")
-    @PutMapping("/api/v1/posts/{id}")
+    @PutMapping("/{id}")
     public ResponseEntity<PostDto> updatePost(@Valid @RequestBody PostDto postDto, @PathVariable(name = "id") long id){
 
        PostDto postResponse = postService.updatePost(postDto, id);
 
        return new ResponseEntity<>(postResponse, HttpStatus.OK);
     }
 
+    @Operation(
+            summary = "Delete Post REST API",
+            description = "Delete Post REST API is used to delete a particular post from the database"
+    )
+    @ApiResponse(
+            responseCode = "200",
+            description = "Http Status 200 SUCCESS"
+    )
+    @SecurityRequirement(
+            name = "Bear Authentication"
+    )
     // delete post rest api
     @PreAuthorize("hasRole('ADMIN')")
-    @DeleteMapping("/api/v1/posts/{id}")
+    @DeleteMapping("/{id}")
     public ResponseEntity<String> deletePost(@PathVariable(name = "id") long id){
 
         postService.deletePostById(id);
@@ -68,7 +124,7 @@ public ResponseEntity<String> deletePost(@PathVariable(name = "id") long id){
 
     // Build Get Posts by Category REST API
     // http://localhost:8080/api/posts/category/3
-    @GetMapping("/api/v1/posts/category/{id}")
+    @GetMapping("/category/{id}")
     public ResponseEntity<List<PostDto>> getPostsByCategory(@PathVariable("id") Long categoryId){
         List<PostDto> postDtos = postService.getPostsByCategory(categoryId);
         return ResponseEntity.ok(postDtos);

src/main/java/com/springboot/blog/payload/PostDto.java

@@ -1,31 +1,47 @@
 package com.springboot.blog.payload;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 import jakarta.validation.constraints.NotEmpty;
 import jakarta.validation.constraints.Size;
 import java.util.Set;
 
 @Data
+@Schema(
+        description = "PostDto Model Information"
+)
 public class PostDto {
     private long id;
 
+    @Schema(
+            description = "Blog Post Title"
+    )
     // title should not be null  or empty
     // title should have at least 2 characters
     @NotEmpty
     @Size(min = 2, message = "Post title should have at least 2 characters")
     private String title;
 
+    @Schema(
+            description = "Blog Post Description"
+    )
     // post description should be not null or empty
     // post description should have at least 10 characters
     @NotEmpty
     @Size(min = 10, message = "Post description should have at least 10 characters")
     private String description;
 
+    @Schema(
+            description = "Blog Post Content"
+    )
     // post content should not be null or empty
     @NotEmpty
     private String content;
     private Set<CommentDto> comments;
 
+    @Schema(
+            description = "Blog Post Category"
+    )
     private Long categoryId;
 }