[ICC-275] Redoc + GitHub Pages API 문서 자동 배포 구축

[GulSauce]

📢 설명

Redoc + GitHub Pages로 API 문서 자동 배포 파이프라인을 구축하고, CI/CD 워크플로우 파일명을 역할 기반으로 정리

H2 필요한 이유: 스프링부트가 실행되어야해서, 데이터베이스 자체에 쿼리를 날리거나 그런건 아닙니다!!

변경 요약

#	변경	설명	영향 범위
1	CI/CD 워크플로우 파일명 정리	ci-/cd- 접두사로 역할 기반 네이밍 통일	.github/workflows/
2	API 문서 자동 배포 파이프라인	CI에서 OpenAPI spec 추출 → Redoc + GitHub Pages 배포	CI, app/build.gradle, 설정 파일
3	Git hooks 실행 권한 부여	.githooks/ 파일에 실행 권한(755) 추가	.githooks/

---

변경 1: CI/CD 워크플로우 파일명 역할 기반 정리

워크플로우 파일이 늘어나면서 파일명만으로 역할을 식별하기 어려워져, ci-/cd- 접두사 + 역할 설명 패턴으로 네이밍 컨벤션을 통일했다.

• ci.yml → ci-check-code-convention.yml
• prod_deploy.yml → cd-prod_deploy.yml
• auto-version-bump.yml → ci-auto-version-bump.yml

Note

GitHub Actions는 .github/workflows/ 하위 디렉토리를 지원하지 않으므로, 파일명 접두사 방식이 사실상 유일한 정리 방법이다.

---

변경 2: Redoc + GitHub Pages API 문서 자동 배포 파이프라인

기존에 노션에 API 명세를 수동 기입하는 방식이었으나, 관리가 안 되는 문제가 있었다. 코드 기반으로 OpenAPI spec을 자동 추출하고 Redoc으로 정적 HTML 문서를 생성하여 GitHub Pages에 배포하는 파이프라인을 구축했다.

동작 흐름:

1. develop 브랜치에 Java 소스 또는 application*.yml 변경이 push되면 트리거
2. CI에서 test 프로파일(H2 인메모리 DB)로 서버 기동
3. /v3/api-docs에서 OpenAPI spec JSON 추출
4. Redoc CDN으로 렌더링하는 docs/api/index.html과 함께 GitHub Pages에 배포

설정 파일 구조 개편:

• application-api-docs.yml 삭제 → test 프로파일로 통합 (CI와 테스트가 같은 설정을 공유하여 유지보수 부담 제거)
• application.yml을 spring.application.name만 남기고 최소화 (각 프로파일이 독립적으로 전체 설정 보유)
• app/build.gradle에 H2 runtimeOnly 의존성 추가

💡 의사 선택과정 (trade-off)

API 문서 도구 선정

후보	장점	단점
Swagger UI	SpringDoc 기본 제공	서버 기동 필요, 단일 컬럼
Spring REST Docs	테스트 기반 정확성	작성 비용 높음
Redoc	오픈소스 무료, 정적 HTML, 설명과 코드 예시를 한 화면에서 볼 수 있는 레이아웃	-

CI 프로파일 전략

• CI 전용 프로파일(api-docs) 별도 유지 → 설정 변경 시 두 파일 관리 필요
• test 프로파일 통합 채택 → CI OpenAPI 추출 + 테스트 코드에서 @ActiveProfiles("test")로 공유

---

변경 3: Git hooks 실행 권한 부여

.githooks/pre-commit, prepare-commit-msg의 파일 권한을 644 → 755로 변경. 실행 권한이 없으면 core.hooksPath로 설정해도 훅이 동작하지 않을 수 있다.

---

변경 4: application-test.yml 파일을 스테이징 시킴

API 스키마를 추출하기 위해서는 스프링부트를 일시적으로 구동시켜야한다. 그 때 사용할 프로필이다. 동시에 추후 테스트 코드 작성시에 사용할 프로필로도 활용가능하게 여지를 두었다

코드 설명: 인라인 코멘트

PR의 주요 코드 라인에 인라인 코멘트가 등록되어 있습니다. Files changed 탭에서 확인하세요.

✅ 체크리스트

재현 확인

• develop 머지 후 GitHub Actions에서 API 문서 배포 워크플로우 성공 확인
• GitHub Pages(https://q-asker.github.io/api/)에 Redoc 문서가 정상 배포되었는지 확인

기본

• 의사 선택 과정이 적절한지 확인
• 코드 리뷰

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. 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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 945f385c-ad55-4233-b417-1b1a5822e97d

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch ICC-275-api-docs

---

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

[GulSauce]

📝 코드 설명 코멘트

[GulSauce]

Java 소스 또는 application*.yml 변경 시에만 트리거되도록 paths 필터 적용. README 등 문서만 변경했을 때 불필요한 배포를 방지한다.

[GulSauce]

H2는 CI 환경(test 프로파일)에서 OpenAPI spec 추출 시 인메모리 DB로만 사용되므로 runtimeOnly로 선언. 프로덕션 빌드에는 영향 없음.

[GulSauce]

임시 파일: 스테이징 안한줄 알았는데 해버렸네요 ㅠㅠ
기존 lambda에서 다시 스프링부트로 통합하기위해 두었습니다

[lhoju0158]

확인했습니다