-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #29 from KNU-HAEDAL-Website/feat-swagger-issue-24
feat: Swagger 문서 작성을 위한 기능 구현
- Loading branch information
Showing
21 changed files
with
388 additions
and
19 deletions.
There are no files selected for viewing
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
214 changes: 214 additions & 0 deletions
214
src/main/java/com/haedal/haedalweb/config/SwaggerConfig.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,214 @@ | ||
| package com.haedal.haedalweb.config; | ||
|
|
||
| import com.haedal.haedalweb.constants.ErrorCode; | ||
| import com.haedal.haedalweb.constants.ResponseCode; | ||
| import com.haedal.haedalweb.constants.SuccessCode; | ||
| import com.haedal.haedalweb.dto.ErrorResponse; | ||
| import com.haedal.haedalweb.dto.SuccessResponse; | ||
| import com.haedal.haedalweb.swagger.ApiErrorCodeExample; | ||
| import com.haedal.haedalweb.swagger.ApiErrorCodeExamples; | ||
| import com.haedal.haedalweb.swagger.ApiSuccessCodeExample; | ||
| import com.haedal.haedalweb.swagger.ApiSuccessCodeExamples; | ||
| import com.haedal.haedalweb.swagger.ExampleHolder; | ||
| import io.swagger.v3.oas.annotations.OpenAPIDefinition; | ||
| import io.swagger.v3.oas.annotations.info.Info; | ||
| import io.swagger.v3.oas.models.Components; | ||
| import io.swagger.v3.oas.models.OpenAPI; | ||
| import io.swagger.v3.oas.models.Operation; | ||
| import io.swagger.v3.oas.models.examples.Example; | ||
| import io.swagger.v3.oas.models.media.Content; | ||
| import io.swagger.v3.oas.models.media.MediaType; | ||
| import io.swagger.v3.oas.models.responses.ApiResponse; | ||
| import io.swagger.v3.oas.models.responses.ApiResponses; | ||
| import io.swagger.v3.oas.models.security.SecurityRequirement; | ||
| import io.swagger.v3.oas.models.security.SecurityScheme; | ||
| import org.springdoc.core.customizers.OperationCustomizer; | ||
| import org.springframework.context.annotation.Bean; | ||
| import org.springframework.context.annotation.Configuration; | ||
| import org.springframework.http.HttpHeaders; | ||
| import org.springframework.validation.FieldError; | ||
| import org.springframework.web.method.HandlerMethod; | ||
|
|
||
| import java.util.ArrayList; | ||
| import java.util.Arrays; | ||
| import java.util.List; | ||
| import java.util.Map; | ||
| import java.util.stream.Collectors; | ||
|
|
||
|
|
||
| @OpenAPIDefinition( | ||
| info = @Info(title = "HAEDAL-WEB API 명세서", | ||
| description = "해달 웹 백엔드 API", | ||
| version = "1.0") | ||
|
|
||
| ) | ||
| @Configuration | ||
| public class SwaggerConfig { | ||
| private static final String BEARER_TOKEN_PREFIX = "Bearer"; | ||
|
|
||
| @Bean | ||
| public OpenAPI openAPI() { | ||
| String accessToken = "Access Token (Bearer)"; | ||
|
|
||
| SecurityRequirement securityRequirement = new SecurityRequirement() | ||
| .addList(accessToken); | ||
|
|
||
| SecurityScheme accessTokenSecurityScheme = new SecurityScheme() | ||
| .type(SecurityScheme.Type.HTTP) | ||
| .scheme(BEARER_TOKEN_PREFIX) | ||
| .bearerFormat("JWT") | ||
| .in(SecurityScheme.In.HEADER) | ||
| .name(HttpHeaders.AUTHORIZATION); | ||
|
|
||
| Components components = new Components() | ||
| .addSecuritySchemes(accessToken, accessTokenSecurityScheme); | ||
|
|
||
| return new OpenAPI() | ||
| .addSecurityItem(securityRequirement) | ||
| .components(components); | ||
| } | ||
|
|
||
| @Bean | ||
| public OperationCustomizer customize() { | ||
| return (Operation operation, HandlerMethod handlerMethod) -> { | ||
| ApiErrorCodeExamples apiErrorCodeExamples = handlerMethod.getMethodAnnotation( | ||
| ApiErrorCodeExamples.class); | ||
|
|
||
| // @ApiErrorCodeExamples 어노테이션이 붙어있다면 | ||
| if (apiErrorCodeExamples != null) { | ||
| generateResponseCodeResponseExample(operation, apiErrorCodeExamples.value()); | ||
| } else { | ||
| ApiErrorCodeExample apiErrorCodeExample = handlerMethod.getMethodAnnotation( | ||
| ApiErrorCodeExample.class); | ||
|
|
||
| // @ApiErrorCodeExamples 어노테이션이 붙어있지 않고 | ||
| // @ApiErrorCodeExample 어노테이션이 붙어있다면 | ||
| if (apiErrorCodeExample != null) { | ||
| generateResponseCodeResponseExample(operation, apiErrorCodeExample.value()); | ||
| } | ||
| } | ||
|
|
||
| ApiSuccessCodeExamples apiSuccessCodeExamples = handlerMethod.getMethodAnnotation( | ||
| ApiSuccessCodeExamples.class); | ||
|
|
||
| if (apiSuccessCodeExamples != null) { | ||
| generateResponseCodeResponseExample(operation, apiSuccessCodeExamples.value()); | ||
| } else { | ||
| ApiSuccessCodeExample apiSuccessCodeExample = handlerMethod.getMethodAnnotation( | ||
| ApiSuccessCodeExample.class); | ||
|
|
||
| if (apiSuccessCodeExample != null) { | ||
| generateResponseCodeResponseExample(operation, apiSuccessCodeExample.value()); | ||
| } | ||
| } | ||
|
|
||
| return operation; | ||
| }; | ||
| } | ||
|
|
||
| private void generateResponseCodeResponseExample(Operation operation, ResponseCode[] responseCodes) { | ||
| ApiResponses responses = operation.getResponses(); | ||
|
|
||
| Map<Integer, List<ExampleHolder>> statusWithExampleHolders = Arrays.stream(responseCodes) | ||
| .map( | ||
| responseCode -> ExampleHolder.builder() | ||
| .holder(getSwaggerExample(responseCode)) | ||
| .httpStatus(responseCode.getHttpStatus().value()) | ||
| .name(responseCode.name()) | ||
| .build() | ||
| ) | ||
| .collect(Collectors.groupingBy(ExampleHolder::getHttpStatus)); | ||
|
|
||
| addExamplesToResponses(responses, statusWithExampleHolders); | ||
| } | ||
|
|
||
| // 단일 에러 응답값 예시 추가 | ||
| private void generateResponseCodeResponseExample(Operation operation, ResponseCode responseCode) { | ||
| ApiResponses responses = operation.getResponses(); | ||
|
|
||
| // ExampleHolder 객체 생성 및 ApiResponses에 추가 | ||
| ExampleHolder exampleHolder = ExampleHolder.builder() | ||
| .holder(getSwaggerExample(responseCode)) | ||
| .name(responseCode.name()) | ||
| .httpStatus(responseCode.getHttpStatus().value()) | ||
| .build(); | ||
|
|
||
| addExamplesToResponses(responses, exampleHolder); | ||
| } | ||
|
|
||
| // ErrorResponseDto 형태의 예시 객체 생성 | ||
| private Example getSwaggerExample(ResponseCode responseCode) { | ||
| Example example = new Example(); | ||
|
|
||
| if (responseCode instanceof ErrorCode) { | ||
| List<ErrorResponse.ValidationError> validationErrorList = new ArrayList<>(); | ||
|
|
||
| if (responseCode == ErrorCode.INVALID_PARAMETER) { | ||
| FieldError fieldError = new FieldError("objectName", "field", "defaultMessage"); | ||
| validationErrorList.add(ErrorResponse.ValidationError.of(fieldError)); | ||
| } | ||
|
|
||
| ErrorResponse errorResponse = ErrorResponse.builder() | ||
| .code(((ErrorCode) responseCode).getCode()) | ||
| .message(responseCode.getMessage()) | ||
| .errors(validationErrorList) | ||
| .build(); | ||
|
|
||
| example.setValue(errorResponse); | ||
|
|
||
| return example; | ||
| } | ||
|
|
||
|
|
||
| SuccessResponse successResponse = SuccessResponse.builder() | ||
| .success(((SuccessCode) responseCode).getSuccess()) | ||
| .message(responseCode.getMessage()) | ||
| .build(); | ||
|
|
||
| example.setValue(successResponse); | ||
|
|
||
| return example; | ||
| } | ||
|
|
||
| private void addExamplesToResponses(ApiResponses responses, | ||
| Map<Integer, List<ExampleHolder>> statusWithExampleHolders) { | ||
|
|
||
| if (responses != null && responses.containsKey("200")) { | ||
| responses.remove("200"); | ||
| } | ||
|
|
||
| statusWithExampleHolders.forEach( | ||
| (status, v) -> { | ||
| Content content = new Content(); | ||
| MediaType mediaType = new MediaType(); | ||
| ApiResponse apiResponse = new ApiResponse(); | ||
|
|
||
| v.forEach( | ||
| exampleHolder -> mediaType.addExamples( | ||
| exampleHolder.getName(), | ||
| exampleHolder.getHolder() | ||
| ) | ||
| ); | ||
| content.addMediaType("application/json", mediaType); | ||
| apiResponse.setContent(content); | ||
| responses.addApiResponse(String.valueOf(status), apiResponse); | ||
| } | ||
| ); | ||
| } | ||
|
|
||
| private void addExamplesToResponses(ApiResponses responses, ExampleHolder exampleHolder) { | ||
| Content content = new Content(); | ||
| MediaType mediaType = new MediaType(); | ||
| ApiResponse apiResponse = new ApiResponse(); | ||
|
|
||
| mediaType.addExamples(exampleHolder.getName(), exampleHolder.getHolder()); | ||
| content.addMediaType("application/json", mediaType); | ||
| apiResponse.content(content); | ||
|
|
||
| if (responses != null && responses.containsKey("200")) { | ||
| responses.remove("200"); | ||
| } | ||
|
|
||
| responses.addApiResponse(String.valueOf(exampleHolder.getHttpStatus()), apiResponse); | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
9 changes: 9 additions & 0 deletions
9
src/main/java/com/haedal/haedalweb/constants/ResponseCode.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| package com.haedal.haedalweb.constants; | ||
|
|
||
| import org.springframework.http.HttpStatus; | ||
|
|
||
| public interface ResponseCode { | ||
| public HttpStatus getHttpStatus(); | ||
| public String getMessage(); | ||
| public String name(); | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
31 changes: 31 additions & 0 deletions
31
src/main/java/com/haedal/haedalweb/controller/LoginController.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| package com.haedal.haedalweb.controller; | ||
|
|
||
| import com.haedal.haedalweb.constants.ErrorCode; | ||
| import com.haedal.haedalweb.constants.SuccessCode; | ||
| import com.haedal.haedalweb.dto.LoginDTO; | ||
| import com.haedal.haedalweb.swagger.ApiErrorCodeExamples; | ||
| import com.haedal.haedalweb.swagger.ApiSuccessCodeExample; | ||
| import io.swagger.v3.oas.annotations.Operation; | ||
| import io.swagger.v3.oas.annotations.tags.Tag; | ||
| import org.springframework.stereotype.Controller; | ||
| import org.springframework.web.bind.annotation.PostMapping; | ||
| import org.springframework.web.bind.annotation.RequestBody; | ||
|
|
||
| @Tag(name = "로그인 관련 API") | ||
| @Controller | ||
| public class LoginController { | ||
|
|
||
| @Operation(summary = "로그인 API") | ||
| @ApiSuccessCodeExample(SuccessCode.LOGIN_SUCCESS) | ||
| @ApiErrorCodeExamples({ErrorCode.INVALID_LOGIN_CONTENTS_TYPE, ErrorCode.FAILED_LOGIN}) | ||
| @PostMapping("/login") | ||
| public void signIn(@RequestBody LoginDTO loginDTO) { | ||
| } | ||
|
|
||
| @Operation(summary = "로그아웃 API") | ||
| @ApiSuccessCodeExample(SuccessCode.LOGOUT_SUCCESS) | ||
| @ApiErrorCodeExamples({ErrorCode.NULL_REFRESH_TOKEN, ErrorCode.INVALID_REFRESH_TOKEN, ErrorCode.EXPIRED_REFRESH_TOKEN}) | ||
| @PostMapping("/logout") | ||
| public void signIn() { | ||
| } | ||
| } |
Oops, something went wrong.