Skip to content

refactor: Swagger 코드를 인터페이스로 분리 #78

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 4, 2024
Merged

refactor: Swagger 코드를 인터페이스로 분리 #78

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 4 additions & 36 deletions server/src/main/java/sunflower/server/api/TranslationApiController.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,5 @@
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;
Expand All @@ -29,26 +23,12 @@
@RequiredArgsConstructor
@RestController
@RequestMapping("/translations")
@Tag(name = "점자 번역 API", description = "Sunny Braille 핵심 기능으로, 점역 작업을 담당합니다.")
public class TranslationApiController {
public class TranslationApiController implements TranslationApiControllerDocs {

private final TranslationService translationService;

@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<PdfRegisterResponse> registerPdf(
@Parameter(name = "file", description = "점역할 pdf 파일", required = true,
example = "쎈_3124번.pdf", schema = @Schema(type = "file"))
@RequestPart("file") MultipartFile file
) {
public ResponseEntity<PdfRegisterResponse> registerPdf(@RequestPart("file") MultipartFile file) {
if (file.isEmpty()) {
throw new FileEmptyException(1, "빈 파일입니다.");
}
Expand All @@ -60,26 +40,14 @@ public ResponseEntity<PdfRegisterResponse> registerPdf(
.body(PdfRegisterResponse.from(file.getOriginalFilename()));
}

@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(
@Parameter(description = "Translations id", required = true) @PathVariable("id") Long id) {
public ResponseEntity<TranslationStatusResponse> checkStatus(@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(
@Parameter(description = "Translations id", required = true) @PathVariable("id") Long id) {
public ResponseEntity<BrfFileQueryResponse> queryBrfFile(@PathVariable("id") Long id) {
final String brfContent = translationService.findBrfFileById(id);
final BrfFileQueryResponse response = BrfFileQueryResponse.from(id, brfContent);
return ResponseEntity.ok(response);
Expand Down
50 changes: 50 additions & 0 deletions server/src/main/java/sunflower/server/api/TranslationApiControllerDocs.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
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 org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestPart;
import org.springframework.web.multipart.MultipartFile;
import sunflower.server.api.response.BrfFileQueryResponse;
import sunflower.server.api.response.PdfRegisterResponse;
import sunflower.server.api.response.TranslationStatusResponse;

@Tag(name = "점자 번역 API", description = "Sunny Braille 핵심 기능으로, 점역 작업을 담당합니다.")
public interface TranslationApiControllerDocs {

@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
))
ResponseEntity<PdfRegisterResponse> registerPdf(
@Parameter(name = "file", description = "점역할 pdf 파일", required = true,
example = "쎈_3124번.pdf", schema = @Schema(type = "file"))
@RequestPart("file") MultipartFile file
);

@Operation(summary = "점역 상황 체크 API", description = "id와 함께 요청하면 점역 진행 상황을 반환하며, 클라이언트의 progress bar 표시를 위해 사용해 주세요.")
@ApiResponse(responseCode = "200", description = "점역 진행 상황을 반환합니다.",
content = {
@Content(mediaType = "application/json", schema = @Schema(implementation = TranslationStatusResponse.class))
})
ResponseEntity<TranslationStatusResponse> checkStatus(
@Parameter(description = "Translations id", required = true) @PathVariable("id") Long id);

@Operation(summary = "점역 결과 BRF 파일 반환 API", description = "id와 함께 요청하면 점역 결과를 반환합니다.")
@ApiResponse(responseCode = "200", description = "점역된 결과를 반환합니다..",
content = {
@Content(mediaType = "application/json", schema = @Schema(implementation = BrfFileQueryResponse.class))
})
ResponseEntity<BrfFileQueryResponse> queryBrfFile(
@Parameter(description = "Translations id", required = true) @PathVariable("id") Long id);
}