docs: Swagger API 문서 작성 (#62)

* chore: 의존성 추가 * chore: update submodules * chore: add dependency for springdoc * chore: swagger config * feat: Swagger 작성 * chore: update submodules
sunnybraille · Feb 27, 2024 · 852c0d9 · 852c0d9
1 parent b634652
commit 852c0d9
Show file tree

Hide file tree

Showing 7 changed files with 93 additions and 6 deletions.
diff --git a/server/build.gradle b/server/build.gradle
@@ -26,10 +26,13 @@ dependencies {
     implementation 'org.springframework.boot:spring-boot-starter-web'
     implementation 'com.google.code.gson:gson:2.8.8'
     implementation 'io.jsonwebtoken:jjwt-api:0.11.2'
+    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'
+
     compileOnly 'org.projectlombok:lombok'
     runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.11.2'
     runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.11.2'
     runtimeOnly 'com.h2database:h2'
+
     annotationProcessor 'org.projectlombok:lombok'
     testImplementation 'org.springframework.boot:spring-boot-starter-test'
     testImplementation 'io.rest-assured:rest-assured:5.3.1'

diff --git a/server/src/main/java/sunflower/server/api/HealthCheckApiController.java b/server/src/main/java/sunflower/server/api/HealthCheckApiController.java
@@ -1,12 +1,22 @@
 package sunflower.server.api;
 
+import io.swagger.v3.oas.annotations.Operation;
+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 org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RestController;
 
 @RestController
+@Tag(name = "서버 헬스 체크", description = "서버가 작동중인지 확인하는 API")
 public class HealthCheckApiController {
 
+    @Operation(summary = "헬스 체크 API", description = "서버가 작동중인지 확인합니다.")
+    @ApiResponses(value = {
+            @ApiResponse(responseCode = "200", description = "Server is running properly."),
+            @ApiResponse(responseCode = "500", description = "Server is not running properly.")
+    })
     @GetMapping("/health")
     public ResponseEntity<Void> healthCheck() {
         return ResponseEntity.ok().build();

diff --git a/server/src/main/java/sunflower/server/api/TranslationApiController.java b/server/src/main/java/sunflower/server/api/TranslationApiController.java
@@ -1,5 +1,11 @@
 package sunflower.server.api;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+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.tags.Tag;
 import lombok.RequiredArgsConstructor;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -17,15 +23,31 @@
 
 import java.net.URI;
 
+import static org.springframework.http.MediaType.MULTIPART_FORM_DATA_VALUE;
+
 @RequiredArgsConstructor
 @RestController
 @RequestMapping("/translations")
+@Tag(name = "점자 번역 API", description = "Sunny Braille 핵심 기능으로, 점역 작업을 담당합니다.")
 public class TranslationApiController {
 
     private final TranslationService translationService;
 
-    @PostMapping
-    public ResponseEntity<Void> registerPdf(@RequestPart("file") MultipartFile file) {
+    @Operation(summary = "PDF 점자 번역 요청 API", description = "점역 작업은 서버에서 비동기적으로 처리되며, id만 즉시 반환됩니다.")
+    @ApiResponse(responseCode = "201", description = "PDF가 성공적으로 업로드되었습니다.",
+            headers =
+            @io.swagger.v3.oas.annotations.headers.Header(
+                    name = "Location",
+                    description = "Translations id(해바라기에서 제공하는 id)",
+                    schema = @Schema(type = "long"),
+                    required = true
+            ))
+    @PostMapping(consumes = MULTIPART_FORM_DATA_VALUE)
+    public ResponseEntity<Void> registerPdf(
+            @Parameter(name = "file", description = "점역할 pdf 파일", required = true,
+                    example = "쎈_3124번.pdf", schema = @Schema(type = "file"))
+            @RequestPart("file") MultipartFile file
+    ) {
         if (file.isEmpty()) {
             throw new FileEmptyException(1, "빈 파일입니다.");
         }
@@ -37,17 +59,28 @@ public ResponseEntity<Void> registerPdf(@RequestPart("file") MultipartFile file)
                 .build();
     }
 
+    @Operation(summary = "점역 상황 체크 API", description = "id와 함께 요청하면 점역 진행 상황을 반환하며, 클라이언트의 progress bar 표시를 위해 사용해 주세요.")
+    @ApiResponse(responseCode = "200", description = "점역 진행 상황을 반환합니다.",
+            content = {
+                    @Content(mediaType = "application/json", schema = @Schema(implementation = TranslationStatusResponse.class))
+            })
     @GetMapping("/{id}/status")
-    public ResponseEntity<TranslationStatusResponse> checkStatus(@PathVariable("id") Long id) {
+    public ResponseEntity<TranslationStatusResponse> checkStatus(
+            @Parameter(description = "Translations id", required = true) @PathVariable("id") Long id) {
         final TranslationStatusDto dto = translationService.status(id);
         return ResponseEntity.ok(TranslationStatusResponse.from(dto));
     }
 
+    @Operation(summary = "점역 결과 BRF 파일 반환 API", description = "id와 함께 요청하면 점역 결과를 반환합니다.")
+    @ApiResponse(responseCode = "200", description = "점역된 결과를 반환합니다..",
+            content = {
+                    @Content(mediaType = "application/json", schema = @Schema(implementation = BrfFileQueryResponse.class))
+            })
     @GetMapping("/{id}")
-    public ResponseEntity<BrfFileQueryResponse> queryBrfFile(@PathVariable("id") Long id) {
+    public ResponseEntity<BrfFileQueryResponse> queryBrfFile(
+            @Parameter(description = "Translations id", required = true) @PathVariable("id") Long id) {
         final String brfContent = translationService.findBrfFileById(id);
         final BrfFileQueryResponse response = BrfFileQueryResponse.from(id, brfContent);
         return ResponseEntity.ok(response);
     }
 }
-
diff --git a/server/src/main/java/sunflower/server/api/response/BrfFileQueryResponse.java b/server/src/main/java/sunflower/server/api/response/BrfFileQueryResponse.java
@@ -1,11 +1,16 @@
 package sunflower.server.api.response;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Getter;
 
 @Getter
 public class BrfFileQueryResponse {
 
+    @Schema(description = "Translations ID", defaultValue = "1")
     private final Long id;
+
+    @Schema(description = "brf 파일 내용",
+            defaultValue = "  \\documentclass82#ajpt;081article\"0\n\\usepackage82utf#h;081inputenc\"0\n\\usepackage82T#a;081fontenc\"0\n\\usepackage81CJKutf#h\"0\n\\usepackage81amsmath\"0\n\\usepackage81amsfonts\"0\n\\usepackage81amssymb\"0\n\\usepackage82version=#d;081mhchem\"0\n\\usepackage81stmaryrd\"0\n\n\\begin81document\"0\n\\begin81CJK\"081UTF#h\"081mj\"0\n\\begin81enumerate\"0\n  \\setcounter81enumi\"081#bg\"0\n  \\item $p<q$ q im ,u,m $p\" q$ n irj<: $p^81#b\"0 q<n \\leq p q^81#b\"0$ ! e3.x,ofocz .<*,m $n$ w @r,m$ #cjh o1 ,ir\" $p+q$ w $b'! @mj,ou4 82#d.s5;0\n\\end81enumerate\"0\n\n\\end81CJK\"0\n\\end81document\"0â ")
     private final String content;
 
     public BrfFileQueryResponse(final Long id, final String content) {

diff --git a/server/src/main/java/sunflower/server/api/response/TranslationStatusResponse.java b/server/src/main/java/sunflower/server/api/response/TranslationStatusResponse.java
@@ -1,5 +1,6 @@
 package sunflower.server.api.response;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Getter;
 import lombok.RequiredArgsConstructor;
 import sunflower.server.application.dto.TranslationStatusDto;
@@ -8,10 +9,21 @@
 @RequiredArgsConstructor
 public class TranslationStatusResponse {
 
+    @Schema(description = "Translations ID", defaultValue = "1")
     private final Long id;
+
+    @Schema(description = "OCR 진행 상태", defaultValue = "PROCESSING",
+            allowableValues = {"NONE", "PROCESSING", "COMPLETED"})
     private final String ocrStatus;
+
+    @Schema(description = "OCR 진행도", defaultValue = "30%")
     private final Integer ocrPercentDone;
+
+    @Schema(description = "점역 진행 상태", defaultValue = "NONE",
+            allowableValues = {"NONE", "PROCESSING", "COMPLETED"})
     private final String brailleTranslationsStatus;
+
+    @Schema(description = "점역 진행도", defaultValue = "0%")
     private final Integer brailleTranslationPercentDone;
 
     public static TranslationStatusResponse from(final TranslationStatusDto dto) {

diff --git a/server/src/main/java/sunflower/server/config/SwaggerConfig.java b/server/src/main/java/sunflower/server/config/SwaggerConfig.java
@@ -0,0 +1,24 @@
+package sunflower.server.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 {
+    @Bean
+    public OpenAPI openAPI() {
+        return new OpenAPI()
+                .components(new Components())
+                .info(apiInfo());
+    }
+
+    private Info apiInfo() {
+        return new Info()
+                .title("Sunny Braille API")
+                .description("Sunny Braille API")
+                .version("1.0.0");
+    }
+}
diff --git a/server/src/main/resources/security b/server/src/main/resources/security