API Documentation

📘 API 문서화 전략: Spring REST Docs + OpenAPI + ReDoc

(프로젝트 초기 단계 기준 / 향후 확장 고려)

---

1. 선택 배경

• 현재 API 규모가 크지 않아 테스트 기반 문서화 흐름을 도입하기 좋은 시점
• 코드에 annotation을 과도하게 추가하고 싶지 않음
• 문서와 실제 API 동작 간 정합성을 높이고 싶음
• 문서 생성 과정에서 수동 작업을 최소화하고 싶음
• UI 기반 문서(예: ReDoc/Swagger)도 필요
• 추후 API 증가 시 문서 전략을 유연하게 확장할 수 있어야 함

---

2. Spring REST Docs를 우선 도입한 이유

• 테스트 기반 문서화

  • 테스트에서 실제 요청/응답을 기반으로 스니펫 생성
  • 문서 정확성 향상

• 코드 오염 없음

  • Swagger처럼 DTO/Controller에 annotation을 추가할 필요 없음

• CI/CD와 자연스럽게 연동

  • 테스트 실행 → 스니펫 생성 → 문서 자동 생성

• 현재 API가 많지 않아 학습·관리 비용이 적음

※ 테스트 커버리지를 100%로 맞출 필요는 없고, 필요한 API만 테스트 기반 문서화 대상으로 관리하면 됨.

---

3. OpenAPI 자동 생성 + ReDoc UI 선택 이유

Spring REST Docs의 단점(직접 index.adoc 조립, UI 부재)을 해결하기 위해 다음을 조합함:

• spring-restdocs-openapi

  • 스니펫을 기반으로 OpenAPI 3.0 스펙(YAML) 자동 생성
  • 사람 손으로 문서를 조립할 필요 없음

• ReDoc UI

  • 자동 생성된 OpenAPI YAML을 기반으로 가독성 높은 API 문서 UI 제공
  • 프론트엔드·QA·외부 협력자가 보기 편함

최종 흐름

테스트 → 스니펫 생성 → OpenAPI YAML → ReDoc UI

완전 자동화 구조.

---

4. 향후 확장성 (springdoc-openapi 고려)

REST Docs는 지금 프로젝트 상황에 가장 적합하지만, API가 많아지고 문서 요구사항이 복잡해지면 아래와 같이 확장 가능:

• Swagger 기반의 springdoc-openapi 도입 고려 가능
• 일부 API만 Swagger로 문서화하는 혼합 전략도 가능
• 백오피스/외부용/내부용 문서를 구분해 생성하는 구조로 전환 가능
• ReDoc + Swagger UI 동시 제공도 가능

현재 선택은 **“현 시점에서 가장 효율적이고 확장 가능한 선택”**이라는 의미.

---

5. 결론

Spring REST Docs + OpenAPI 자동 생성 + ReDoc UI 조합은

• 테스트 기반의 정확한 문서
• 자동 생성되어 유지보수 부담 적음
• 코드 오염 없음
• UI 기반 문서 제공
• 향후 Swagger(Springdoc)로 자연스럽게 전환 가능

이라는 장점을 가진 프로젝트 초기 단계의 최적 문서화 방식이다.