[Redoc 시리즈 03] API 문서에 브랜드 입히기: 테마 커스터마이징과 고급 옵션 가이드

API Documentation Series: Redoc 완결

API 문서의 완성은 디테일,
Redoc 테마 커스터마이징

 

안녕하세요, code-resting입니다. Redoc 시리즈의 마지막 편입니다! 지난 2편에서는 Spring Boot 연동법을 알아보았는데요. 오늘은 한 걸음 더 나아가, 기본 디자인을 탈피해 우리만의 독창적인 API 문서를 만드는 법을 공유합니다. 폰트, 컬러, 그리고 개발자들의 필수 조건인 다크 모드 설정까지 모두 다뤄보겠습니다.

1. Theme 객체 이해하기

Redoc은 theme 속성을 통해 거의 모든 UI 요소의 색상과 크기를 제어할 수 있습니다. 가장 기본적인 구조는 다음과 같습니다.

Redoc.init(spec, {
  theme: {
    colors: {
      primary: { main: '#eb2f96' }, // 브랜드 메인 컬러
      success: { main: '#52c41a' }
    },
    typography: {
      fontFamily: 'Pretendard, sans-serif',
      fontSize: '15px'
    }
  }
}, document.getElementById('redoc-container'));

2. 개발자의 로망, 다크 모드(Dark Mode) 적용

Redoc은 공식적으로 '다크 모드 스위치'를 제공하지는 않지만, 테마 설정을 통해 완벽한 다크 테마를 구현할 수 있습니다.

핵심 설정 포인트:

• sidebar.backgroundColor를 어두운 톤으로 설정
• rightPanel.backgroundColor와 코드 블록 테마 일치시키기
• 본문 텍스트 색상(colors.text.primary)을 밝은 회색으로 변경

3. 유용한 고급 옵션들

가독성을 높여주는 Redoc만의 필살기 옵션들입니다.

• disableSearch: false - API가 많을 때 상단 검색창은 필수입니다.
• hideDownloadButton: true - API 명세 원본(JSON/YAML) 노출을 막고 싶을 때 사용합니다.
• expandResponses: "200,201" - 성공 응답 결과가 항상 펼쳐져 있도록 설정하여 가독성을 높입니다.

4. 로고 및 파비콘 커스터마이징

사이드바 최상단에 서비스 로고를 배치하면 훨씬 전문적인 인상을 줍니다.

logo: {
  url: 'https://your-site.com/logo.png',
  href: 'https://your-site.com/'
}

💡 시리즈를 마치며

총 3편에 걸친 Redoc 시리즈를 통해 "단순한 정보 전달을 넘어 시각적으로도 완벽한 API 문서"를 만드는 법을 알아보았습니다. 문서는 개발자 간의 약속이자 서비스의 얼굴입니다. 이제 뻔한 Swagger UI 대신, 우리만의 테마가 입혀진 Redoc으로 팀의 품격을 높여보세요!

© 2026 code-resting. All rights reserved.