feat(global): swagger 설정 #31
Conversation
- swaggerConfig 생성 - 의존성 추가 - security 내 swagger 접근 경로 명시
|
""" Walkthrough이번 변경사항은 Swagger(OpenAPI) 기반의 API 문서화를 위한 설정과 주석 추가, 그리고 Swagger UI 접근을 위한 보안 및 CORS 정책의 보완이 포함되어 있습니다. 또한, Swagger 프로필 활성화 시 글로벌 예외처리기가 비활성화되도록 조정되었습니다. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant SwaggerUI
participant SpringApp
participant SecurityConfig
participant SwaggerConfig
User->>SwaggerUI: Swagger UI 접속 요청 (/swagger-ui/)
SwaggerUI->>SpringApp: API 문서 및 엔드포인트 정보 요청 (/v3/api-docs)
SpringApp->>SwaggerConfig: OpenAPI 문서 및 JWT 인증 스키마 반환
SpringApp->>SecurityConfig: 인증 필요 여부 확인 (Swagger 관련 경로는 permitAll)
SpringApp-->>SwaggerUI: OpenAPI 문서 응답
User->>SpringApp: API 호출 (JWT 토큰 포함)
SpringApp->>SecurityConfig: JWT 인증 처리
SpringApp-->>User: API 응답
Possibly related PRs
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
✨ Finishing Touches
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (7)
src/main/java/com/example/gtable/global/config/CorsConfig.java (1)
18-18: 허용 Origin 리스트의 하드코딩은 설정 파일로 분리하는 편이 좋습니다추가된
http://localhost:8083도 개발용 도메인으로 보이는데, 운영 반영 시 Origin 을 분기하기 쉽도록application-*.yml또는 환경변수로 옮기면 유지보수가 수월합니다.src/main/java/com/example/gtable/global/config/SwaggerConfig.java (1)
15-29: Swagger 설정 잘 추가되었습니다!JWT 보안 스킴까지 포함되어 있어 기본 문서화에는 문제가 없어 보입니다.
추가로, API 버전·타이틀과 같은 메타데이터를application.yml프로퍼티로 분리하면 배포 파이프라인에서 쉽게 변경할 수 있습니다.src/main/java/com/example/gtable/bookmark/controller/BookmarkController.java (5)
18-20: Swagger 어노테이션 Import 추가 확인
Swagger 문서화를 위한 주요 어노테이션을 잘 임포트하셨습니다.
만약 JWT 보안 스키마를 메서드나 클래스 레벨에 적용할 계획이라면io.swagger.v3.oas.annotations.security.SecurityRequirement도 함께 임포트해주세요.
22-22: 클래스 레벨 @tag 활용
@Tag로 API 그룹화를 잘 적용하셨습니다.
추가로 전체 BookmarkController가 JWT 인증이 필요하다면 클래스 레벨에@SecurityRequirement(name = "bearerAuth")를 달아 보안 스키마를 문서에 연결해보세요.
30-31: createBookmark 메서드 문서화 보강 제안
@Operation과@ApiResponse(responseCode = "201")만 선언되었는데,
- PathVariable(
storeId) 파라미터 설명을 위한@Parameter- 400/401/404 등 주요 에러 응답을 명시한
@ApiResponses- 메서드별 보안 요구사항(
@SecurityRequirement)
등을 추가하면 더욱 완성도 높은 API 스펙이 됩니다.
44-45: getAllBookmarks 메서드 응답 예시 확대 제안
성공(200) 이외에도
- 인증 실패(401)
- 권한 없음(403)
등을@ApiResponse로 문서화하시고, 반환 타입도 제네릭(ResponseEntity<ApiResponse<...>>)으로 구체화하면 API 사용자 입장에서 가독성이 높아집니다.
56-57: deleteBookmark 메서드 추가 문서화 추천
삭제 성공(200) 외에
- 잘못된 bookmarkId(400/404)
- 인증 문제(401/403)
등 주요 시나리오를@ApiResponse로 보강하고,@SecurityRequirement를 달아 보안 스킴을 연결하면 문서 완성도가 올라갑니다.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
build.gradle(1 hunks)src/main/java/com/example/gtable/bookmark/controller/BookmarkController.java(3 hunks)src/main/java/com/example/gtable/global/config/CorsConfig.java(1 hunks)src/main/java/com/example/gtable/global/config/SecurityConfig.java(1 hunks)src/main/java/com/example/gtable/global/config/SwaggerConfig.java(1 hunks)src/main/java/com/example/gtable/global/security/exception/GlobalExceptionHandler.java(2 hunks)
🔇 Additional comments (2)
build.gradle (1)
54-56: Swagger 의존성 버전 호환성 확인이 필요합니다
springdoc-openapi-starter-webmvc-ui:2.6.0은 Spring Boot 3.5 라인과 호환되지만, 간혹 스프링 부트 마이너 릴리스에 따라 transitive 버전 충돌이 보고됩니다.
빌드 후 애플리케이션 구동-시NoSuchMethodError등이 발생하지 않는지 한 번 더 확인 부탁드립니다.
필요하다면 BOM(version catalog) 을 사용해 의존성 버전을 일관성 있게 관리하는 것도 고려해 주세요.src/main/java/com/example/gtable/global/security/exception/GlobalExceptionHandler.java (1)
24-26:@Profile("!swagger")적용 범위 재확인 권장Swagger 프로필에서 전역 예외처리를 완전히 비활성화하면 500 에러가 그대로 노출될 수 있습니다.
API 문서용으로 특정 예외만 제외하려는 의도라면@ConditionalOnMissingBean또는 개별@ExceptionHandler메서드에 조건부 프로파일을 두는 방식을 고려해 보세요.
- security 내 swagger 접근 경로 오타 수정
작업 요약
Issue Link
#28
문제점 및 어려움
해결 방안
Reference
Summary by CodeRabbit
신규 기능
버그 수정
기타