이론을 넘어 구현으로!
Spring Boot와 Redoc의 완벽한 조화
안녕하세요, code-resting입니다. 지난 1편에서는 왜 우리가 Redoc을 써야 하는지 그 장점을 살펴보았습니다. 오늘은 그 실천 편으로, Spring Boot 프로젝트에서 생성된 OpenAPI 스펙을 활용해 Redoc 페이지를 띄우는 2가지 방식을 실전 코드를 통해 알아보겠습니다.
1. 시작은 springdoc-openapi부터
Redoc은 자체적으로 문서를 생성하는 것이 아니라, openapi.json 파일을 읽어와서 시각화합니다. 먼저 Spring Boot에 관련 의존성을 추가합니다.
// build.gradle
dependencies {
implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.3.0'
}설정 후 앱을 실행하고 /v3/api-docs에 접속했을 때 JSON 형태의 명세가 나온다면 준비는 끝났습니다.
2. 방식 1: 간단한 HTML 임베딩 (CDN)
별도의 빌드 도구 없이 static 폴더 아래 HTML 파일 하나만 만들어도 Redoc을 띄울 수 있습니다. 가장 빠르고 가벼운 방법입니다.
<!-- src/main/resources/static/docs/index.html -->
<!DOCTYPE html>
<html>
<head>
<title>API Reference</title>
<meta charset="utf-8"/>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
</head>
<body>
<redoc spec-url='/v3/api-docs'></redoc>
</body>
</html>이제 localhost:8080/docs/index.html로 접속하면 아름다운 Redoc 화면을 만날 수 있습니다.
3. 방식 2: redoc-cli를 활용한 정적 파일 빌드
실무에서는 보안이나 성능상의 이유로 런타임에 JSON을 읽기보다, 빌드 시점에 독립적인 HTML 파일로 뽑아내는 방식을 선호합니다.
터미널에서 빌드하기 (Node.js 기반)
npx @redocly/cli build-docs openapi.json -o index.html이 과정을 GitHub Actions나 Jenkins 파이프라인에 추가하면 배포될 때마다 최신 API 문서가 자동으로 호스팅 서버(S3, GitHub Pages 등)로 전달됩니다.
4. 어떤 방식을 선택해야 할까?
| 항목 | HTML 임베딩 (CDN) | CLI 정적 빌드 |
|---|---|---|
| 구현 난이도 | 매우 쉬움 | 보통 (빌드 환경 필요) |
| 로딩 속도 | 보통 (JS 파싱 필요) | 빠름 (단일 파일) |
| 권장 환경 | 내부 프로젝트, 사이드 | 기업용 외부 공개 API |
💡 마무리하며
Spring Boot와 Redoc의 연동은 생각보다 간단하지만, 그 결과물이 주는 협업의 가치는 엄청납니다. 프론트엔드 개발자나 외부 파트너에게 Swagger 대신 Redoc 링크를 전달해 보세요. 팀의 전문성이 한 단계 더 높아 보일 것입니다. 다음 3편에서는 Redoc의 꽃, 테마 커스터마이징과 다크 모드 설정에 대해 다뤄보겠습니다.
'스프링 > Spring-Docs' 카테고리의 다른 글
| [Redoc 시리즈 03] API 문서에 브랜드 입히기: 테마 커스터마이징과 고급 옵션 가이드 (0) | 2026.03.15 |
|---|---|
| [Redoc 시리즈 01] 개발자가 사랑하는 API 문서, Redoc을 선택해야 하는 이유 (0) | 2026.03.13 |
| 죽은 문서는 가라! Spring REST Docs로 100% 신뢰할 수 있는 API 명세서 만들기 (0) | 2026.03.11 |
| AsciiDoctor 문법 (0) | 2021.02.09 |
| Spring-Docs (0) | 2021.02.09 |
댓글