feat: Swagger API 문서 추가

[smiinii]

🔗 연관된 이슈

• close chore: swagger 적용 #111

📋 작업 내용

• springdoc-openapi 3.1.0을 적용했습니다.
• API 문서를 용도에 따라 user-api, admin-api, internal-api 그룹으로 분리했습니다.
• Swagger 첫 화면의 기본 그룹을 user-api로 설정했습니다.
• 사용자 API의 X-User-Id 인증 헤더를 Swagger에서 입력할 수 있도록 구성했습니다.
• 게시물, 주제, 사용자, 사인 이미지 처리 콜백 API의 요청·응답·오류 응답을 문서화했습니다.
• 실제 구현에서 발생할 수 있는 누락된 404 응답을 문서에 추가했습니다.
  • 게시물 목록 조회
  • 회원 탈퇴
  • 사인 이미지 업로드 URL 발급
  • 사인 이미지 수정
• 운영 환경에서는 OpenAPI JSON과 Swagger UI가 노출되지 않도록 비활성화했습니다.
• README에 Swagger 접근 방법과 API 그룹, springdoc 3.1.0 유지 근거를 기록했습니다.
• 전체 테스트와 Swagger UI 렌더링을 확인했습니다.

✅ 변경 사항 체크리스트

• PR 대상 브랜치가 develop인가요?
• Linear 동기화 여부를 확인했나요?

📎 참고 자료

• 로컬 Swagger UI: http://localhost:8080/swagger-ui.html
• springdoc 3.1.0 경고 이슈: SpringDocUtils logs Json Processing Exception occurred warning for every @Min-constrained Integer query parameter (regression since 3.1.0) springdoc/springdoc-openapi#3314
• 관련 수정 PR: fix: Add a type deserializer to allow for JSON cloning of a JsonSchema object springdoc/springdoc-openapi#3315

🛠️ Technical Concerns

• Spring Boot 4 지원을 위해 springdoc-openapi 3.1.0을 사용했습니다.
• 3.1.0에서는 Bean Validation 제약이 붙은 숫자 파라미터를 문서화할 때 경고 로그가 발생하는 알려진 회귀 문제가 있습니다.
• 현재 OpenAPI JSON, 스키마 생성 및 Swagger UI 렌더링에는 문제가 없어 3.1.0을 유지합니다.
• 수정 사항이 포함된 정식 버전이 출시되면 해당 버전으로 업그레이드할 예정입니다.
• Swagger UI 주소에 urls.primaryName 쿼리 파라미터가 있으면 설정된 기본 그룹보다 해당 값이 우선됩니다.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 195b3ea1-8038-43f6-b588-bba7934430a7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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