refactor: Hashids 난독화에 따른 Swagger 문서화 전역 자동화 (#55)

Author: ckdals4600

src/main/java/com/sofa/linkiving/domain/chat/controller/ChatApi.java

@@ -10,7 +10,6 @@
 import com.sofa.linkiving.domain.chat.dto.response.MessagesRes;
 import com.sofa.linkiving.domain.member.entity.Member;
 import com.sofa.linkiving.global.common.BaseResponse;
-import com.sofa.linkiving.global.config.annotation.DecodeHash;
 
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
@@ -68,10 +67,8 @@ public interface ChatApi {
 	BaseResponse<MessagesRes> getMessages(
 		Member member,
 		@Parameter(description = "채팅방 ID")
-		@DecodeHash
 		Long chatId,
 		@Parameter(description = "페이징을 위한 마지막 메시지 ID, 첫 조회 시 null")
-		@DecodeHash
 		Long lastId,
 		@Parameter(description = "페이지 크기")
 		@Min(value = 1, message = "최소 1개 이상 조회해야 합니다.")
@@ -89,7 +86,7 @@ BaseResponse<CreateChatRes> createChat(
 	);
 
 	@Operation(summary = "링크 삭제", description = "해당 링크방과 채팅 기록을 전부 Hard Delete 진행합니다.")
-	BaseResponse<String> deleteChat(Member member, @DecodeHash Long chatId);
+	BaseResponse<String> deleteChat(Member member, @Parameter(description = "채팅방 ID") Long chatId);
 
 	void sendMessage(AnswerReq req, Member member);
 

src/main/java/com/sofa/linkiving/domain/chat/controller/FeedbackApi.java

@@ -6,11 +6,13 @@
 import com.sofa.linkiving.global.common.BaseResponse;
 
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.tags.Tag;
 
 @Tag(name = "Feedback", description = "피드백 관리 API")
 public interface FeedbackApi {
 	@Operation(summary = "피드백 추가 및 수정", description = "메세지에 피드백을 추가 및 수정하고 피드백 ID를 반환합니다.")
-	BaseResponse<UpsertFeedbackRes> upsertFeedback(Long messageId, UpsertFeedbackReq createFeedbackReq,
+	BaseResponse<UpsertFeedbackRes> upsertFeedback(@Parameter(description = "메세지 ID") Long messageId,
+		UpsertFeedbackReq createFeedbackReq,
 		Member member);
 }

src/main/java/com/sofa/linkiving/domain/link/controller/LinkApi.java

@@ -38,6 +38,8 @@
 			**CASE A: PROCESSING (처리 중)**
 				```json
 				{
+					"linkId": aB9x2K8R,
+					"status": "PROCESSING"
 					"linkId": 1,
 					"status": "PROCESSING",
 					"summary": null,
@@ -48,10 +50,10 @@
 		**CASE B: COMPLETED (요약 완료)**
 				```json
 				{
-					"linkId": 1,
+					"linkId": aB9x2K8R,
 					"status": "COMPLETED",
 					"summary": {
-						"id": 100,
+						"id": aB9x2K8S,
 						"content": "생성된 AI 요약 내용입니다."
 					},
 					"errorMessage": null
@@ -60,7 +62,7 @@
 		**CASE C: FAILED (요약 실패)**
 				```json
 				{
-					"linkId": 1,
+					"linkId": aB9x2K8R,
 					"status": "FAILED",
 					"summary": null,
 					"errorMessage": "AI 서버 응답이 없습니다."

src/main/java/com/sofa/linkiving/domain/link/dto/response/LinkDuplicateCheckRes.java

@@ -9,7 +9,7 @@ public record LinkDuplicateCheckRes(
 	@Schema(description = "URL 중복 여부", example = "true")
 	boolean exists,
 
-	@Schema(description = "중복된 링크 ID (exists가 true일 때만 반환)", example = "123")
+	@Schema(description = "중복된 링크 ID (exists가 true일 때만 반환)")
 	@JsonSerialize(using = HashidsSerializer.class)
 	Long linkId
 ) {

src/main/java/com/sofa/linkiving/domain/member/dto/response/MemberProfileRes.java

@@ -11,7 +11,7 @@
 
 @Builder
 public record MemberProfileRes(
-	@Schema(description = "회원 ID", example = "1")
+	@Schema(description = "회원 ID")
 	@JsonSerialize(using = HashidsSerializer.class)
 	Long id,
 	@Schema(description = "유저명", example = "Linkiving User")

src/main/java/com/sofa/linkiving/global/config/SwaggerConfig.java

@@ -0,0 +1,70 @@
+package com.sofa.linkiving.global.config;
+
+import org.springdoc.core.customizers.ParameterCustomizer;
+import org.springdoc.core.customizers.PropertyCustomizer;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.sofa.linkiving.global.config.annotation.DecodeHash;
+
+import io.swagger.v3.oas.models.media.StringSchema;
+
+@Configuration
+public class SwaggerConfig {
+
+	@Bean
+	public ParameterCustomizer hashidParameterCustomizer() {
+		return (parameterModel, methodParameter) -> {
+			if (methodParameter.hasParameterAnnotation(DecodeHash.class)) {
+				parameterModel.setSchema(new StringSchema());
+				parameterModel.setExample("aB9x2K8R");
+				String currentDesc = parameterModel.getDescription() != null ? parameterModel.getDescription() : "";
+				if (!currentDesc.contains("해시")) {
+					parameterModel.setDescription(currentDesc + " (해시 문자열)");
+				}
+			}
+			return parameterModel;
+		};
+	}
+
+	@Bean
+	public PropertyCustomizer hashidPropertyCustomizer() {
+		return (property, type) -> {
+			if (type.getCtxAnnotations() == null) {
+				return property;
+			}
+
+			boolean isHashidField = false;
+
+			for (java.lang.annotation.Annotation annotation : type.getCtxAnnotations()) {
+
+				if (annotation instanceof JsonSerialize serialize) {
+					if (serialize.using().getSimpleName().contains("Hashids")) {
+						isHashidField = true;
+						break;
+					}
+				} else if (annotation instanceof JsonDeserialize deserialize) {
+					if (deserialize.using().getSimpleName().contains("Hashids")) {
+						isHashidField = true;
+						break;
+					}
+				}
+			}
+
+			if (isHashidField) {
+				property.setType("string");
+				property.setFormat(null);
+				property.setExample("aB9x2K8R");
+
+				String desc = property.getDescription() != null ? property.getDescription() : "";
+				if (!desc.contains("해시")) {
+					property.setDescription(desc + " (해시된 문자열)");
+				}
+			}
+
+			return property;
+		};
+	}
+}