Ignore: 🔧 Swagger 에러 정의 어노테이션

pennyway-app-external-api/src/main/java/kr/co/pennyway/api/apis/ledger/api/SpendingApi.java

@@ -14,7 +14,10 @@
 import kr.co.pennyway.api.apis.ledger.dto.SpendingIdsDto;
 import kr.co.pennyway.api.apis.ledger.dto.SpendingReq;
 import kr.co.pennyway.api.apis.ledger.dto.SpendingSearchRes;
+import kr.co.pennyway.api.common.annotation.ApiExceptionExplanation;
+import kr.co.pennyway.api.common.annotation.ApiResponseExplanations;
 import kr.co.pennyway.api.common.security.authentication.SecurityUserDetails;
+import kr.co.pennyway.domain.domains.spending.exception.SpendingErrorCode;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
 import org.springframework.validation.annotation.Validated;
@@ -64,19 +67,12 @@ public interface SpendingApi {
 
     @Operation(summary = "지출 내역 상세 조회", method = "GET", description = "지출 내역의 ID값으로 해당 지출의 상세 내역을 반환합니다.")
     @Parameter(name = "spendingId", description = "지출 내역 ID", example = "1", required = true, in = ParameterIn.PATH)
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", content = @Content(schemaProperties = @SchemaProperty(name = "spending", schema = @Schema(implementation = SpendingSearchRes.Individual.class)))),
-            @ApiResponse(responseCode = "404", description = "NOT_FOUND", content = @Content(examples = {
-                    @ExampleObject(name = "지출 내역 조회 오류",
-                            value = """
-                                    {
-                                    "code": "4040",
-                                    "message": "존재하지 않는 지출 내역입니다."
-                                    }
-                                    """
-                    )
-            }))
-    })
+    @ApiResponse(responseCode = "200", content = @Content(schemaProperties = @SchemaProperty(name = "spending", schema = @Schema(implementation = SpendingSearchRes.Individual.class))))
+    @ApiResponseExplanations(
+            errors = {
+                    @ApiExceptionExplanation(name = "지출 내역 조회 오류", description = "NOT_FOUND", value = SpendingErrorCode.class, constant = "NOT_FOUND_SPENDING")
+            }
+    )
     ResponseEntity<?> getSpendingDetail(@PathVariable Long spendingId, @AuthenticationPrincipal SecurityUserDetails user);
 
     @Operation(summary = "지출 내역 수정", method = "PUT", description = """
@@ -101,7 +97,6 @@ public interface SpendingApi {
     }))
     ResponseEntity<?> deleteSpending(@PathVariable Long spendingId, @AuthenticationPrincipal SecurityUserDetails user);
 
-
     @Operation(summary = "지출 내역 복수 삭제", method = "DELETE", description = "사용자의 지출 내역의 ID목록으로 해당 지출 내역들을 삭제 합니다.")
     @ApiResponse(responseCode = "403", description = "지출 내역에 대한 권한이 없습니다.", content = @Content(examples = {
             @ExampleObject(name = "지출 내역 권한 오류", description = "지출 내역에 대한 권한이 없습니다.",

pennyway-app-external-api/src/main/java/kr/co/pennyway/api/common/annotation/ApiExceptionExplanation.java

@@ -0,0 +1,27 @@
+package kr.co.pennyway.api.common.annotation;
+
+import kr.co.pennyway.common.exception.BaseErrorCode;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface ApiExceptionExplanation {
+    Class<? extends BaseErrorCode> value();
+
+    /**
+     * BaseErrorCode를 구현한 Enum 클래스의 상수명
+     */
+    String constant();
+
+    String name() default "";
+
+    String mediaType() default "application/json";
+
+    String summary() default "";
+
+    String description() default "";
+}

pennyway-app-external-api/src/main/java/kr/co/pennyway/api/common/annotation/ApiResponseExplanations.java

@@ -0,0 +1,12 @@
+package kr.co.pennyway.api.common.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface ApiResponseExplanations {
+    ApiExceptionExplanation[] errors() default {};
+}

pennyway-app-external-api/src/main/java/kr/co/pennyway/api/common/swagger/ApiExceptionExplainParser.java

@@ -0,0 +1,87 @@
+package kr.co.pennyway.api.common.swagger;
+
+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 kr.co.pennyway.api.common.annotation.ApiExceptionExplanation;
+import kr.co.pennyway.api.common.annotation.ApiResponseExplanations;
+import kr.co.pennyway.api.common.response.ErrorResponse;
+import kr.co.pennyway.common.exception.BaseErrorCode;
+import lombok.AccessLevel;
+import lombok.Builder;
+import org.springframework.util.StringUtils;
+import org.springframework.web.method.HandlerMethod;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+public final class ApiExceptionExplainParser {
+    public static void parse(Operation operation, HandlerMethod handlerMethod) {
+        ApiResponseExplanations annotation = handlerMethod.getMethodAnnotation(ApiResponseExplanations.class);
+
+        if (annotation != null) {
+            generateExceptionResponseDocs(operation, annotation.errors());
+        }
+    }
+
+    private static void generateExceptionResponseDocs(Operation operation, ApiExceptionExplanation[] exceptions) {
+        ApiResponses responses = operation.getResponses();
+
+        Map<Integer, List<ExampleHolder>> holders = Arrays.stream(exceptions)
+                .map(ExampleHolder::from)
+                .collect(Collectors.groupingBy(ExampleHolder::httpStatus));
+
+        addExamplesToResponses(responses, holders);
+    }
+
+    private static void addExamplesToResponses(ApiResponses responses, Map<Integer, List<ExampleHolder>> holders) {
+        holders.forEach((httpStatus, exampleHolders) -> {
+            Content content = new Content();
+            MediaType mediaType = new MediaType();
+            ApiResponse response = new ApiResponse();
+
+            exampleHolders.forEach(holder -> mediaType.addExamples(holder.name(), holder.holder()));
+            content.addMediaType("application/json", mediaType);
+            response.setContent(content);
+
+            responses.addApiResponse(String.valueOf(httpStatus), response);
+        });
+    }
+
+    @Builder(access = AccessLevel.PRIVATE)
+    private record ExampleHolder(int httpStatus, String name, String mediaType, String description, Example holder) {
+        static ExampleHolder from(ApiExceptionExplanation annotation) {
+            BaseErrorCode errorCode = getErrorCode(annotation);
+
+            return ExampleHolder.builder()
+                    .httpStatus(errorCode.causedBy().statusCode().getCode())
+                    .name(StringUtils.hasText(annotation.name()) ? annotation.name() : errorCode.getExplainError())
+                    .mediaType(annotation.mediaType())
+                    .description(annotation.description())
+                    .holder(createExample(errorCode, annotation.summary(), annotation.description()))
+                    .build();
+        }
+
+        @SuppressWarnings("unchecked")
+        public static <E extends Enum<E> & BaseErrorCode> E getErrorCode(ApiExceptionExplanation annotation) {
+            Class<E> enumClass = (Class<E>) annotation.value();
+            return Enum.valueOf(enumClass, annotation.constant());
+        }
+
+        private static Example createExample(BaseErrorCode errorCode, String summary, String description) {
+            ErrorResponse response = ErrorResponse.of(errorCode.causedBy().getCode(), errorCode.getExplainError());
+
+            Example example = new Example();
+            example.setValue(response);
+            example.setSummary(summary);
+            example.setDescription(description);
+
+            return example;
+        }
+    }
+}

pennyway-app-external-api/src/main/java/kr/co/pennyway/api/config/SwaggerConfig.java

@@ -4,16 +4,20 @@
 import io.swagger.v3.oas.annotations.servers.Server;
 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.info.Info;
 import io.swagger.v3.oas.models.security.SecurityRequirement;
 import io.swagger.v3.oas.models.security.SecurityScheme;
+import kr.co.pennyway.api.common.swagger.ApiExceptionExplainParser;
 import lombok.RequiredArgsConstructor;
+import org.springdoc.core.customizers.OperationCustomizer;
 import org.springdoc.core.models.GroupedOpenApi;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 import org.springframework.core.env.Environment;
 import org.springframework.util.ObjectUtils;
 import org.springframework.web.filter.ForwardedHeaderFilter;
+import org.springframework.web.method.HandlerMethod;
 
 @Configuration
 @OpenAPIDefinition(
@@ -38,7 +42,6 @@ public OpenAPI openAPI() {
 
         return new OpenAPI()
                 .info(apiInfo(activeProfile))
-                .addServersItem(new io.swagger.v3.oas.models.servers.Server().url(""))
                 .addSecurityItem(securityRequirement)
                 .components(securitySchemes());
     }
@@ -50,6 +53,7 @@ public GroupedOpenApi allApi() {
         return GroupedOpenApi.builder()
                 .packagesToScan(targets)
                 .group("전체 보기")
+                .addOperationCustomizer(customizer())
                 .build();
     }
 
@@ -60,6 +64,7 @@ public GroupedOpenApi authApi() {
         return GroupedOpenApi.builder()
                 .packagesToScan(targets)
                 .group("사용자 인증")
+                .addOperationCustomizer(customizer())
                 .build();
     }
 
@@ -70,6 +75,7 @@ public GroupedOpenApi userApi() {
         return GroupedOpenApi.builder()
                 .packagesToScan(targets)
                 .group("사용자 기본 기능")
+                .addOperationCustomizer(customizer())
                 .build();
     }
 
@@ -80,6 +86,7 @@ public GroupedOpenApi storageApi() {
         return GroupedOpenApi.builder()
                 .packagesToScan(targets)
                 .group("정적 파일 저장")
+                .addOperationCustomizer(customizer())
                 .build();
     }
 
@@ -90,6 +97,7 @@ public GroupedOpenApi ledgerApi() {
         return GroupedOpenApi.builder()
                 .packagesToScan(targets)
                 .group("지출 관리")
+                .addOperationCustomizer(customizer())
                 .build();
     }
 
@@ -100,6 +108,7 @@ public GroupedOpenApi backOfficeApi() {
         return GroupedOpenApi.builder()
                 .packagesToScan(targets)
                 .group("백오피스")
+                .addOperationCustomizer(customizer())
                 .build();
     }
 
@@ -108,6 +117,14 @@ ForwardedHeaderFilter forwardedHeaderFilter() {
         return new ForwardedHeaderFilter();
     }
 
+    @Bean
+    public OperationCustomizer customizer() {
+        return (Operation operation, HandlerMethod handlerMethod) -> {
+            ApiExceptionExplainParser.parse(operation, handlerMethod);
+            return operation;
+        };
+    }
+
     private Components securitySchemes() {
         final var securitySchemeAccessToken = new SecurityScheme()
                 .name(JWT)