ReDoc#
ReDoc은 OpenAPI(이전의 Swagger) 명세를 기반으로 한 오픈 소스 API 문서 생성 도구이다. 2016년에 Rebilly에 의해 개발된 이 도구는 단일 HTML 파일로 깔끔하고 반응형 있는 API 문서를 생성하는 데 특화되어 있다.
ReDoc의 핵심 가치는 세 가지이다:
- 개발자 친화적 인터페이스: 사용하기 쉽고 탐색하기 쉬운 문서 제공
- 시각적 매력: 미학적으로 세련된 문서 생성
- 유연성과 맞춤화: 다양한 요구에 맞게 조정 가능
ReDoc의 주요 기능#
단일 페이지 디자인#
ReDoc은 단일 페이지 애플리케이션(SPA) 접근 방식을 취한다. 이는 사용자가 페이지를 전환하지 않고도 모든 API 문서에 접근할 수 있음을 의미한다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| <!-- 기본적인 ReDoc 통합 -->
<!DOCTYPE html>
<html>
<head>
<title>API 문서</title>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
</head>
<body>
<redoc spec-url="https://petstore.swagger.io/v2/swagger.json"></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
</body>
</html>
|
세 패널 레이아웃#
ReDoc의 인터페이스는 세 개의 주요 패널로 구성된다:
- 왼쪽: 탐색 메뉴로, 모든 엔드포인트와 모델의 개요 제공
- 중앙: 선택한 엔드포인트에 대한 자세한 설명
- 오른쪽: 요청 및 응답 스키마와 예제
이 레이아웃은 개발자가 API를 이해하고 사용하는 데 필요한 모든 정보를 한눈에 볼 수 있게 해준다.
반응형 디자인#
ReDoc은 모바일 기기부터 대형 데스크톱 화면까지 모든 화면 크기에 맞게 조정된다. 이는 개발자가 이동 중에도 API 문서를 쉽게 참조할 수 있게 해준다.
코드 샘플 지원#
OpenAPI 명세에 정의된 코드 샘플(x-code-samples 확장)을 지원하여 다양한 프로그래밍 언어로 API를 어떻게 사용하는지 보여줄 수 있다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| # OpenAPI 명세의 코드 샘플 예제
paths:
/users:
get:
summary: 사용자 목록 조회
x-code-samples:
- lang: JavaScript
source: |
fetch('https://api.example.com/users')
.then(response => response.json())
.then(data => console.log(data));
- lang: Python
source: |
import requests
response = requests.get('https://api.example.com/users')
data = response.json()
print(data)
|
검색 기능#
ReDoc은 강력한 검색 기능을 제공하여 사용자가 엔드포인트, 매개변수, 모델 등을 빠르게 찾을 수 있게 한다.
테마 맞춤화#
로고, 색상, 폰트 등을 통해 문서를 회사 브랜드와 일치시킬 수 있다.
1
2
3
4
5
6
| <redoc
spec-url="https://petstore.swagger.io/v2/swagger.json"
theme-options="{'logo': {'gutter': '20px', 'url': 'https://example.com/logo.png'},
'colors': {'primary': {'main': '#32329f'}},
'typography': {'fontFamily': 'Arial, sans-serif'}}">
</redoc>
|
ReDoc 설치 및 사용 방법#
CDN 사용 (가장 간단한 방법)#
1
2
| <redoc spec-url="경로/swagger.json"></redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
|
NPM을 통한 설치#
1
2
3
4
5
| # NPM 설치
npm install redoc --save
# 또는 Yarn 사용
yarn add redoc
|
React 애플리케이션에서 사용:
1
2
3
4
5
6
7
8
9
10
11
12
13
| import { RedocStandalone } from 'redoc';
const ApiDocs = () => (
<RedocStandalone
specUrl="path/to/swagger.json"
options={{
nativeScrollbars: true,
theme: { colors: { primary: { main: '#00abff' } } }
}}
/>
);
export default ApiDocs;
|
CLI 도구 사용#
ReDoc CLI를 사용하면 정적 HTML 파일을 생성할 수 있다:
1
2
3
4
5
| # ReDoc CLI 설치
npm install -g redoc-cli
# HTML 파일 생성
redoc-cli bundle openapi.yaml -o index.html
|
ReDoc과 OpenAPI/Swagger 통합#
ReDoc은 OpenAPI 명세(버전 2.0, 3.0 및 3.1)와 원활하게 작동한다. 명세는 YAML 또는 JSON 형식일 수 있으며, 로컬 파일이나 URL을 통해 제공될 수 있다.
OpenAPI 명세 요소 활용#
ReDoc은 다음과 같은 OpenAPI 명세 요소를 특별히 활용한다:
- 태그(tags): 엔드포인트 그룹화 및 탐색 메뉴 구성
- 설명(descriptions): Markdown 지원으로 풍부한 텍스트 형식
- x-tagGroups: 여러 태그를 상위 그룹으로 구성
- x-code-samples: 다양한 언어의 코드 예제 표시
예제:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
| openapi: 3.0.0
info:
title: 샘플 API
version: 1.0.0
description: |
# 소개
이 API는 사용자 관리를 위한 엔드포인트를 제공합니다.
## 인증
모든 요청에는 Bearer 토큰이 필요합니다.
x-tagGroups:
- name: 핵심 리소스
tags:
- 사용자
- 인증
tags:
- name: 사용자
description: 사용자 관리 엔드포인트
paths:
/users:
get:
tags:
- 사용자
summary: 모든 사용자 조회
x-code-samples:
- lang: curl
source: curl -H "Authorization: Bearer TOKEN" https://api.example.com/users
|
ReDoc 고급 기능 및 맞춤화#
스타일 맞춤화#
ReDoc은 theme-options 속성을 통해 광범위한 스타일 맞춤화를 제공한다:
1
2
3
4
5
6
7
8
9
10
11
12
13
| const options = {
theme: {
typography: {
fontSize: '16px',
headings: { fontFamily: 'Montserrat, sans-serif' }
},
sidebar: {
backgroundColor: '#f5f5f5',
textColor: '#333333'
},
// 기타 스타일 옵션
}
};
|
확장성 및 플러그인#
ReDoc은 플러그인 시스템을 통해 확장될 수 있으며, 커스텀 컴포넌트도 통합할 수 있다.
서버 렌더링#
검색 엔진 최적화(SEO)와 성능을 위한 서버 사이드 렌더링(SSR) 지원:
1
2
3
4
5
6
7
8
| import { renderToString } from 'react-dom/server';
import { createStore } from 'redoc';
import { Redoc, RedocRawOptions } from '@redoc/react';
const renderStaticRedoc = async (spec, options = {}) => {
const store = await createStore(spec, options);
return renderToString(<Redoc store={store} />);
};
|
ReDoc vs. 다른 API 문서화 도구#
ReDoc vs. Swagger UI#
- ReDoc: 더 깔끔하고 미학적인 디자인, 더 나은 렌더링 성능, 단일 페이지 레이아웃
- Swagger UI: 상호작용 기능 강조, API 테스트 콘솔 내장, 넓은 사용자 기반
ReDoc vs. Stoplight Elements#
- ReDoc: 더 간단한 설정, 더 가벼운 크기
- Stoplight Elements: 더 많은 맞춤화 옵션, 더 현대적인 UI
ReDoc vs. Slate#
- ReDoc: OpenAPI 명세 기반, 명세로부터 자동 생성
- Slate: 보다 일반적인 문서화 도구, 더 많은 수동 작업 필요하지만 더 큰 유연성 제공
ReDoc의 실제 사용 사례#
- GitHub API
GitHub은 자사의 API 문서화에 ReDoc을 활용하여 개발자들에게 명확하고 탐색하기 쉬운 인터페이스를 제공한다. - 금융 및 결제 API
Stripe와 같은 금융 서비스 API는 ReDoc을 사용하여 복잡한 금융 개념과 데이터 구조를 명확하게 설명한다. - IoT 및 하드웨어 API
IoT 플랫폼은 ReDoc을 사용하여 다양한 디바이스 및 센서 인터페이스를 문서화한다.
ReDoc 모범 사례#
명확한 태그 구조
효과적인 탐색을 위한 잘 구성된 태그 시스템을 설계한다:
1
2
3
4
5
6
7
8
9
| x-tagGroups:
- name: 핵심 API
tags:
- 인증
- 사용자
- name: 고급 기능
tags:
- 분석
- 보고서
|
풍부한 Markdown 설명
Markdown을 활용하여 정보가 풍부하고 시각적으로 매력적인 설명을 제공한다:
1
2
3
4
5
6
7
8
9
10
11
12
13
| info:
description: |
# API 시작하기
## 인증
모든 요청에는 `Authorization` 헤더가 필요합니다.
```
Authorization: Bearer YOUR_API_KEY
```
## 속도 제한
API는 분당 100개의 요청으로 제한됩니다.
|
철저한 예제
각 엔드포인트에 대해 요청 및 응답 예제를 제공한다:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| paths:
/users:
post:
requestBody:
content:
application/json:
examples:
사용자_생성:
value:
name: "홍길동"
email: "hong@example.com"
responses:
'201':
content:
application/json:
examples:
성공:
value:
id: "123"
name: "홍길동"
email: "hong@example.com"
|
ReDoc의 제한 사항 및 해결 방법#
상호작용 부족
ReDoc은 Swagger UI와 달리 내장된 API 테스트 콘솔을 제공하지 않는다. 해결책으로 Swagger UI와 ReDoc을 함께 제공하거나, 별도의 API 플레이그라운드를 연결할 수 있다.
대규모 API의 성능
매우 큰 API 명세의 경우 성능이 저하될 수 있다.
이를 해결하기 위해:
- 명세를 여러 파일로 분할하고
$ref를 사용하여 참조 - 더 강력한 하드웨어에서 빌드 진행
- 정적 HTML 파일 생성 후 제공
맞춤화 한계
일부 고급 맞춤화 요구 사항은 ReDoc의 기본 옵션으로 충족되지 않을 수 있다. 해결책으로 소스 코드를 포크하여 수정하거나, React 컴포넌트로 ReDoc을 래핑하여 추가 기능을 제공할 수 있다.
ReDoc 개발 및 커뮤니티#
ReDoc은 활발한 오픈 소스 프로젝트로, GitHub(https://github.com/Redocly/redoc)에서 개발되고 있다. 버그 보고, 기능 요청 및 풀 리퀘스트를 통해 프로젝트에 기여할 수 있다.
현재 ReDoc은 Redocly라는 회사에서 유지 관리하고 있으며, 이 회사는 무료 오픈 소스 버전 외에도 엔터프라이즈급 API 문서화 솔루션을 제공한다.
용어 정리#
참고 및 출처#