[URECA-56] Feat: 스웨거 문서 정리

[joonhyong]

Key Changes

• global/config/SweggerConfig

작업 내역

• 스웨거 문서 정리를 하였습니다.

• 이제 스웨거의 Authorization 버튼에 Bearer Token을 입력하여 API들을 테스트를 해 보실 수 있습니다.

• 추후 API 추가 시 Controller.java 파일에 @tag 어노테이션 작성해주면 분류 가능합니다. (문서 정리는 나중에 해도되므로 신경 안쓰셔도 괜찮습니다.)

• close: [URECA-56] Feat: 스웨거 문서 정리 #32

💬 공유사항 to 리뷰어

사용 가이드

1. 개발자 툴 열고 네트워크 탭을 선택한 상태로 로그인을 진행합니다.

2. 네트워크 탭에서 Response탭을 눌러 accessToken을 보고 드래그하여 복사합니다. (Ctrl + C)

3. 스웨거에 접속하여 상단 우측의 Authorization 버튼을 누릅니다. 그리고 복사한 accessToken을 붙여넣기 합니다. (Ctrl + V)

4. 이 후 API 테스트를 진행하시면 401 TOKEN_MISSING 에러가 뜨지 않고 200 OK가 뜹니다.

비고

Summary by CodeRabbit

릴리스 노트

• Documentation

  • 모든 주요 API 엔드포인트에 Swagger/OpenAPI 태그 추가로 API 문서 구조화 개선

• Chores

  • JWT 베어러 인증 스키마 설정 추가
  • Swagger UI 정렬 옵션 구성 추가
  • CORS 및 쿠키 보안 설정을 환경 변수로 매개변수화

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

🎯 Walkthrough

이 변경은 Swagger/OpenAPI 문서화 기능을 정리하고 강화하는 작업입니다. 8개의 컨트롤러 클래스에 @Tag 어노테이션을 추가하여 도메인별로 API를 그룹화했습니다(인증, 예제, STT, 요약). SwaggerConfig 설정 클래스를 신규 생성하여 JWT Bearer 인증 스키마와 4개의 API 태그를 정의했습니다. application.yml에서 Swagger UI 정렬 옵션을 추가하고 CORS 및 쿠키 설정을 환경변수로 매개변수화했습니다.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

---

📋 상세 분석

패턴 반복으로 인한 효율적 검토

컨트롤러 파일 8개에서 동일한 패턴이 반복됩니다:

• io.swagger.v3.oas.annotations.tags.Tag 임포트
• @Tag(name = "X. Category", description = "...") 어노테이션 추가

개선점: 이런 반복 작업은 IDE의 라이브 템플릿이나 코드 생성 도구로 자동화할 수 있습니다.

SwaggerConfig 클래스 검토 포인트

✅ 잘 구현된 부분:

• OpenAPI 빈을 Spring 설정으로 중앙화
• JWT Bearer 보안 스키마 명시적 정의
• 4개 태그의 계층적 구조(숫자 접두사로 정렬)

⚠️ 개선 제안:

• components.addSecuritySchemes() 사용 시, 모든 엔드포인트에 보안 요구사항이 자동 적용되는지 확인하세요. 공개 엔드포인트(회원가입 등)에 불필요한 인증이 요구되지 않는지 테스트 필요합니다.
• 태그 설명이 일부 누락되어 있습니다("2. Exam" — description 없음). 스웨거 UI에서 의도한 대로 보이는지 확인하세요.

application.yml 설정 개선

✅ 좋은 판단:

• CORS_ALLOWED_ORIGINS, COOKIE_SECURE를 환경변수화하여 환경별 유연성 확보
• tags-sorter: alpha, operations-sorter: alpha로 API 문서 정렬 자동화

권장사항: 환경변수 설정 가이드 문서(README 또는 배포 문서)를 업데이트하여 배포팀이 올바르게 설정할 수 있도록 하세요.

---

✨ 결과

이 작업으로 Swagger 문서가 도메인별로 체계화되고 JWT 인증 정보가 명확하게 표시되어 API 클라이언트의 개발 경험이 향상될 것으로 보입니다. 변경 사항이 대부분 메타데이터 레벨이므로 런타임 동작에는 영향이 없습니다. 다만 보안 스키마 자동 적용 범위를 공개 엔드포인트와의 상호작용 관점에서 최종 확인하길 권장합니다.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	PR 제목은 변경 사항의 핵심을 명확하게 요약합니다: Swagger 문서를 정리(분류 및 인증 설정)한다는 의도가 직관적으로 드러납니다.
Linked Issues check	✅ Passed	코드 변경 사항이 연결된 이슈 #32의 요구 사항을 완전히 충족합니다. (1) 도메인별 묶기: 모든 컨트롤러에 @Tag 어노테이션 추가 (2) Authorization 버튼: SwaggerConfig에서 bearerAuth 보안 스키마 정의
Out of Scope Changes check	✅ Passed	모든 변경 사항이 Swagger 문서 정리(태그 분류, 인증 설정, UI 정렬)라는 명확한 스코프 내에 있으며, 비즈니스 로직이나 핵심 기능 변경은 없습니다.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}