[DOCS] Swagger 명세 추가

[buzz0331]

#️⃣연관된 이슈

closes #8

📝작업 내용

스웨거 명세 의존성을 추가했습니다.

상균님이 구현하신 사장님 계좌 관련 crud api도 제가 임의로 명세하긴 했는데 구체적인 api 설명에 관해서는 상균님이 덧붙여주시면 감사하겠습니다~

스크린샷 (선택)

💬리뷰 요구사항(선택)

리뷰어가 특별히 봐주었으면 하는 부분이 있다면 작성해주세요

ex) 메서드 XXX의 이름을 더 잘 짓고 싶은데 혹시 좋은 명칭이 있을까요?

Summary by CodeRabbit

• 신기능

  • Swagger/OpenAPI UI 제공으로 인터랙티브 API 문서 사용 가능
  • JWT Bearer 인증 스키마 지원 및 전역 보안 적용
  • 오류 사례 자동 예시 생성으로 응답 예시 강화

• 개선

  • 점주 계좌 API가 로그인된 사용자 컨텍스트에 연동되어 동작
  • 인증 API에 태그/설명 추가로 문서 가독성 향상

• 설정

  • dev/local/test 프로필에 server.profile·server.http-url 설정 추가
  • 테스트 전용 컨트롤러는 local 프로필에서만 활성화

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Springdoc OpenAPI UI 의존성 추가 및 OpenAPI 설정 클래스와 OperationCustomizer 도입; 컨트롤러·DTO에 Swagger 애노테이션 추가; OwnerController가 @userid로 ownerId를 주입받도록 엔드포인트 시그니처 변경; TestController를 local 프로필로 제한; 환경별 server.profile 및 server.http-url 설정 추가.

Changes

Cohort / File(s)	Summary
Build / OpenAPI 의존성 build.gradle	Springdoc OpenAPI UI 의존성(org.springdoc:springdoc-openapi-starter-webmvc-ui:2.8.8) 추가.
OpenAPI Config & Customizer src/main/java/konkuk/chacall/global/config/OpenApiConfig.java, src/main/resources/application-*.yml, src/test/resources/application-test.yml	OpenAPI 빈 등록(서버 정의, JWT Bearer 보안), OperationCustomizer 추가하여 ExceptionDescription 기반 오류 예시들을 ApiResponse에 주입; dev/local/test에 server.profile 및 server.http-url 설정 추가.
Owner API 변경 src/main/java/konkuk/chacall/domain/owner/presentation/OwnerController.java	@UserId로 ownerId 주입; 은행계좌 CRUD 엔드포인트 시그니처에 ownerId 추가 및 서비스 호출에 전달; Swagger 애노테이션(@tag, @operation, @parameter(hidden), @ExceptionDescription) 추가; 하드코드 ID 제거.
DTO Swagger 메타데이터 .../owner/presentation/dto/request/RegisterBankAccountRequest.java, .../owner/presentation/dto/request/UpdateBankAccountRequest.java	레코드와 필드에 @Schema 추가(설명·예시).
AuthController 문서화 src/main/java/konkuk/chacall/global/common/security/oauth2/auth/AuthController.java	컨트롤러에 @Tag, 메서드에 @Operation 및 @ExceptionDescription 추가; 내부 사용되지 않던 종속성 일부 제거(로직 흐름 유지).
애노테이션 이동/추가 및 리졸버 업데이트 src/main/java/konkuk/chacall/global/common/annotation/ExceptionDescription.java, .../UserId.java, .../security/resolver/UserIdArgumentResolver.java	ExceptionDescription 애노테이션 추가; UserId 패키지 경로 이동(및 관련 import 업데이트); 리졸버 동작 변경 없음.
Swagger 유틸 추가 src/main/java/konkuk/chacall/global/common/swagger/ExampleHolder.java, .../SwaggerResponseDescription.java	ExampleHolder(Lombok @Getter/@builder) 추가; SwaggerResponseDescription 열거형 추가하여 각 API별 ErrorCode 집합 매핑 제공.
로컬 전용 테스트 컨트롤러 src/main/java/konkuk/chacall/domain/test/TestController.java	클래스에 @Profile("local") 추가하여 로컬 프로필에서만 활성화되도록 변경.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant C as Client
  participant D as DispatcherServlet
  participant R as UserIdArgumentResolver
  participant OC as OwnerController
  participant S as OwnerService

  C->>D: HTTP 요청 /owners/bank-accounts...
  activate D
  D->>R: @UserId 해석 요청
  R-->>D: ownerId (JWT에서 추출)
  D->>OC: endpoint(ownerId, ...)
  OC->>S: serviceCall(ownerId, ...)
  S-->>OC: 결과
  OC-->>D: BaseResponse
  D-->>C: HTTP 응답
  deactivate D

Loading

sequenceDiagram
  autonumber
  participant SD as SpringDoc
  participant CFG as OpenApiConfig
  participant OCZ as OperationCustomizer
  participant CT as ControllerMethod
  participant E as ExceptionDescription
  participant SRD as SwaggerResponseDescription
  participant OA as OpenAPI Model

  SD->>CFG: OpenAPI 빈 초기화 (서버, 보안)
  SD->>OCZ: 각 Operation에 커스터마이저 적용
  OCZ->>CT: 애노테이션 검사
  alt @ExceptionDescription 존재
    CT-->>OCZ: ExceptionDescription 값
    OCZ->>SRD: 매핑된 ErrorCode 집합 조회
    SRD-->>OCZ: ErrorCode 리스트
    OCZ->>OA: ApiResponses에 상태별 예시(Examples) 추가
  else 없음
    OCZ-->>SD: 변경 없음
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• [FEAT] 사장님 - 계좌 CRUD 기능 구현 #5 — OwnerController 관련 변경(엔드포인트/서비스 연동)과 직접적 중복 영역 존재.
• [FEAT] 카카오 소셜 로그인 연동 및 인증/인가 필터 도입 #6 — 인증 관련(UserId 애노테이션/리졸버) 이동 및 사용과 연관.
• [CHORE] 초기 프로젝트 설정 #2 — ErrorCode/ErrorResponse 및 전역 핸들러와 OpenAPI 예시 매핑 로직 의존 관계.

Suggested labels

🛠️ feat

Poem

깡총, 문서 밭에 씨앗 심었네 🥕
에러도 예시로 반짝이고, 토끼는 춤추네.
프로필 따라 길을 고르고, 주인 아이디 살짝 건네며,
스웨거 나비가 날아와 API 들판을 비추네.
훌쩍, 문서의 향기로 다시 뛰어간다!

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/#8-swagger

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bce2c98 and 96b58ce.

📒 Files selected for processing (15)

• build.gradle (1 hunks)
• src/main/java/konkuk/chacall/domain/owner/presentation/OwnerController.java (2 hunks)
• src/main/java/konkuk/chacall/domain/owner/presentation/dto/request/RegisterBankAccountRequest.java (1 hunks)
• src/main/java/konkuk/chacall/domain/owner/presentation/dto/request/UpdateBankAccountRequest.java (1 hunks)
• src/main/java/konkuk/chacall/domain/test/TestController.java (1 hunks)
• src/main/java/konkuk/chacall/global/common/annotation/ExceptionDescription.java (1 hunks)
• src/main/java/konkuk/chacall/global/common/annotation/UserId.java (1 hunks)
• src/main/java/konkuk/chacall/global/common/security/oauth2/auth/AuthController.java (2 hunks)
• src/main/java/konkuk/chacall/global/common/security/resolver/UserIdArgumentResolver.java (1 hunks)
• src/main/java/konkuk/chacall/global/common/swagger/ExampleHolder.java (1 hunks)
• src/main/java/konkuk/chacall/global/common/swagger/SwaggerResponseDescription.java (1 hunks)
• src/main/java/konkuk/chacall/global/config/OpenApiConfig.java (1 hunks)
• src/main/resources/application-dev.yml (1 hunks)
• src/main/resources/application-local.yml (1 hunks)
• src/test/resources/application-test.yml (1 hunks)

---

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.}

[ksg1227]

확인했습니다~ 👍🏻