[FEAT #7] swagger 설정

NOW-SOPT-SERVER · May 1, 2024 · cb4c7b9 · cb4c7b9
1 parent 52195f5
commit cb4c7b9
Show file tree

Hide file tree

Showing 8 changed files with 89 additions and 5 deletions.
diff --git a/week_3/3rdSeminar/build.gradle b/week_3/3rdSeminar/build.gradle
@@ -28,6 +28,7 @@ dependencies {
 	runtimeOnly 'org.postgresql:postgresql'
 	annotationProcessor 'org.projectlombok:lombok'
 	implementation 'org.springframework.boot:spring-boot-starter-validation'
+	implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.2'
 	testImplementation 'org.springframework.boot:spring-boot-starter-test'
 }
 

diff --git a/week_3/3rdSeminar/src/main/java/com/sopt/seminar/common/dto/SuccessMessage.java b/week_3/3rdSeminar/src/main/java/com/sopt/seminar/common/dto/SuccessMessage.java
@@ -15,7 +15,7 @@ public enum SuccessMessage {
     MEMBER_FIND_SUCCESS(HttpStatus.OK.value(), "멤버 조회가 완료되었습니다"),
     MEMBER_DELETE_SUCCESS(HttpStatus.OK.value(), "멤버 삭제가 완료되었습니다."),
 
-    POST_CREATE_SUCCESS(HttpStatus.OK.value(), "블로그 글 작성이 완료되었습니다."),
+    POST_CREATE_SUCCESS(HttpStatus.CREATED.value(), "블로그 글 작성이 완료되었습니다."),
     SINGLE_POST_FIND_SUCCESS(HttpStatus.OK.value(), "하나의 블로그 글 조회가 완료되었습니다.");
 
 

diff --git a/week_3/3rdSeminar/src/main/java/com/sopt/seminar/common/dto/SuccessStatusResponse.java b/week_3/3rdSeminar/src/main/java/com/sopt/seminar/common/dto/SuccessStatusResponse.java
@@ -1,10 +1,17 @@
 package com.sopt.seminar.common.dto;
 
 import com.fasterxml.jackson.annotation.JsonInclude;
+import io.swagger.v3.oas.annotations.media.Schema;
 
 public record SuccessStatusResponse<T> (
+
+        @Schema(description = "상태 코드", nullable = false, example = "200")
         int status,
+
+        @Schema(description = "상태 메세지", nullable = false, example = "성공하였습니다.")
         String message,
+
+        @Schema(description = "데이터", nullable = false)
         @JsonInclude(JsonInclude.Include.NON_NULL)
         T data
 ) {

diff --git a/week_3/3rdSeminar/src/main/java/com/sopt/seminar/config/SwaggerConfig.java b/week_3/3rdSeminar/src/main/java/com/sopt/seminar/config/SwaggerConfig.java
@@ -0,0 +1,24 @@
+package com.sopt.seminar.config;
+
+import io.swagger.v3.oas.models.Components;
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.info.Info;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+public class SwaggerConfig {
+
+    //JWT를 사용하지 않은 경우 (JWT 사용 여부에 따라 입력해야 할 내용이 달라진다.)
+    @Bean
+    public OpenAPI openAPI() {
+        Info info = new Info()
+                .title("Seminar Swagger")
+                .description("NOW SOPT 34th Server Part Seminar Swagger dev API")
+                .version("v1");
+
+        return new OpenAPI()
+                .components(new Components())
+                .info(info);
+    }
+}
diff --git a/week_3/3rdSeminar/src/main/java/com/sopt/seminar/controller/PostController.java b/week_3/3rdSeminar/src/main/java/com/sopt/seminar/controller/PostController.java
@@ -3,6 +3,7 @@
 import com.sopt.seminar.common.dto.SuccessStatusResponse;
 import com.sopt.seminar.service.PostService;
 import com.sopt.seminar.service.dto.Request.PostCreateRequest;
+import com.sopt.seminar.service.dto.Response.PostDetailResponse;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.HttpStatus;
@@ -15,23 +16,23 @@
 @RestController
 @RequestMapping("/api/v1")
 @RequiredArgsConstructor
-public class PostController {
+public class PostController implements PostControllerSwagger {
 
     private final PostService postService;
 
     @PostMapping("/posts")
-    public ResponseEntity createPost(
+    public ResponseEntity<SuccessStatusResponse> createPost(
             @RequestHeader Long memberId,
             @RequestHeader Long blogId,
             @Valid @RequestBody PostCreateRequest postCreateRequest
     ){
         postService.createPost(memberId, blogId, postCreateRequest);
-        return ResponseEntity.status(HttpStatus.OK)
+        return ResponseEntity.status(HttpStatus.CREATED)
                 .body(SuccessStatusResponse.of(POST_CREATE_SUCCESS));
     }
 
     @GetMapping("/posts/{postId}")
-    public ResponseEntity<SuccessStatusResponse> getSinglePost(@PathVariable Long postId) {
+    public ResponseEntity<SuccessStatusResponse<PostDetailResponse>> getSinglePost(@PathVariable Long postId) {
         return ResponseEntity.status(HttpStatus.OK)
                 .body(SuccessStatusResponse.of(SINGLE_POST_FIND_SUCCESS, postService.getSinglePost(postId)));
     }

diff --git a/week_3/3rdSeminar/src/main/java/com/sopt/seminar/controller/PostControllerSwagger.java b/week_3/3rdSeminar/src/main/java/com/sopt/seminar/controller/PostControllerSwagger.java
@@ -0,0 +1,42 @@
+package com.sopt.seminar.controller;
+
+import com.sopt.seminar.common.dto.ErrorResponse;
+import com.sopt.seminar.common.dto.SuccessStatusResponse;
+import com.sopt.seminar.service.dto.Request.PostCreateRequest;
+import com.sopt.seminar.service.dto.Response.PostDetailResponse;
+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.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
+
+@Tag(name = "Posts", description = "블로그 글 API")
+public interface PostControllerSwagger {
+
+    @Operation(summary = "글 작성 API")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "글 등록 성공"),
+            @ApiResponse(responseCode = "400", description = "제목과 내용은 필수입니다.",
+                    content = {@Content(schema = @Schema(implementation = ErrorResponse.class))})
+    })
+    ResponseEntity<SuccessStatusResponse> createPost(
+            @RequestHeader Long memberId,
+            @RequestHeader Long blogId,
+            @Valid @RequestBody PostCreateRequest postCreateRequest
+    );
+
+    @Operation(summary = "글 조회 API")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "글 조회 성공"),
+            @ApiResponse(responseCode = "400", description = "ID에 해당하는 작성된 글이 존재하지 않습니다.",
+                    content = {@Content(schema = @Schema(implementation = ErrorResponse.class))})
+    })
+    ResponseEntity<SuccessStatusResponse<PostDetailResponse>> getSinglePost(@PathVariable Long postId);
+}
+
diff --git a/week_3/3rdSeminar/src/main/java/com/sopt/seminar/service/dto/Request/PostCreateRequest.java b/week_3/3rdSeminar/src/main/java/com/sopt/seminar/service/dto/Request/PostCreateRequest.java
@@ -1,13 +1,17 @@
 package com.sopt.seminar.service.dto.Request;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.Size;
 
+@Schema(description = "Post Create request")
 public record PostCreateRequest(
 
+        @Schema(description = "글 제목", example = "블로그 제목 테스트")
         @NotBlank(message = "제목은 필수 값입니다.")
         String title,
 
+        @Schema(description = "글 내용", example = "Hello World!")
         @Size(min = 1, max = 50, message = "내용은 1글자 이상 50글자 이하만 가능합니다.")
         String content
 ) {

diff --git a/..._3/3rdSeminar/src/main/java/com/sopt/seminar/service/dto/Response/PostDetailResponse.java b/..._3/3rdSeminar/src/main/java/com/sopt/seminar/service/dto/Response/PostDetailResponse.java
@@ -1,9 +1,14 @@
 package com.sopt.seminar.service.dto.Response;
 
 import com.sopt.seminar.domain.Post;
+import io.swagger.v3.oas.annotations.media.Schema;
 
+@Schema(description = "Post Detail response")
 public record PostDetailResponse(
+        @Schema(description = "글 제목", example = "블로그 제목 테스트")
         String title,
+
+        @Schema(description = "글 내용", example = "Hello World!")
         String content
 ) {
     public static PostDetailResponse of(Post post) {