Redocly으로 API 문서 만들기
Redocly으로 API 문서 만들기
Redocly이란?
Redocly는 OpenAPI Specification (OAS)을 기반으로 API 문서를 만들어 주는 도구입니다.
Redocly의 장점
Java/Spring Boot 환경에서 springdoc-openapi 같은 라이브러리를 사용하면 Swagger UI를 쉽게 연동할 수 있습니다. 하지만 Redocly는 Swagger UI와 비교했을 때 다음과 같은 뚜렷한 장점을 가집니다.
Redocly의 단점
swagge UI는 API를 직접 테스트 할 수 있지만 Readocly는 테스트를 지원하지 않습니다.
3단 패널 레이아웃(Three-Pane Layout)
Redocly의 가장 큰 특징은 3단 패널 레이아웃(Three-Pane Layout)입니다.
기존 swagger문서는 단일 패널 레이아웃을 채택하고 있습니다. 이 API endpoint가 증가함에 따라 검색이 어렵고, 하나의 패털에서 보기 때문에 API의 parameter가 증가하면 스크롤을 내려서 봐야하는 불편함이 있습니다.
이런 단일 패널의 문제점을 Redocly는 3단 패널 레이아웃을 채택함으로써 가독성을 좋게 만들어줍니다.
- 왼쪽 패널: API 엔드포인트 목록과 검색 기능이 있어 원하는 API를 빠르게 찾을 수 있습니다.
- 중앙 패널: 선택한 API의 상세 설명, 파라미터, 인증 방법 등을 자세히 보여줍니다.
- 오른쪽 패널: 요청 및 응답 예시 코드를 언어별(cURL, Java, Python 등)로 즉시 보여주어 개발자가 API를 사용하는 데 필요한 정보를 한눈에 파악할 수 있습니다.
이 레이아웃 덕분에 사용자는 화면을 계속 스크롤할 필요 없이, 필요한 모든 정보를 한 화면에서 유기적으로 확인할 수 있어 API 탐색 경험이 매우 뛰어납니다.
커스터마이징
Swagger UI는 기본적인 UI 커스터마이징에 한계가 있는 반면, Redocly는 redocly.yaml 설정 파일을 통해 문서의 거의 모든 시각적 요소를 제어할 수 있습니다. 회사 로고를 추가하거나, 브랜드 색상 테마를 적용하고, 폰트를 변경하는 등 세밀한 조정이 가능하여 타 회사와 소통할 때 기업의 아이덴티티를 담은 전문적인 문서를 만들 수 있습니다.
API 문서 품질 관리 (Linting)
코딩 스타일을 검사하는 ESLint나 Checkstyle처럼, Redocly는 API 명세 파일 자체의 품질을 검사하는 Linter 기능을 내장하고 있습니다. 이를 통해 팀 전체가 일관된 스타일과 품질의 API 문서를 작성하도록 할 수 있습니다.
사용법
Redocly은 다양한 방법으로 설치하고 사용 가능합니다.
1. Redocly CLI
1
2
3
4
5
6
7
8
# Redocly CLI 전역 설치
npm install -g @redocly/cli
## 로컬에서 미리보기
redocly preview-docs openapi.yaml
## HTML 파일로 빌드
redocly build-docs openapi.yaml -o index.html
2. npx를 이용한 빌드
1
2
# CLI를 설치하지 않고, openapi.yaml 파일을 빌드하여 index.html 생성
npx @redocly/cli build-docs openapi.yaml -o index.html
3. 웹 페이지에 직접 임베드하기 (CDN 방식)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<!DOCTYPE html>
<html>
<head>
<title>My API Docs</title>
<!-- 필수 메타 태그 -->
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<body>
<!-- spec-url에 공개적으로 접근 가능한 OpenAPI 명세 파일 URL을 지정합니다. -->
<redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
<!-- Redoc 스크립트를 불러옵니다. -->
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
</body>
</html>
custom하기
redocly.yaml 설정 파일을 이용한 커스터마이징
redocly.yaml 설정 파일을 이용한 커스터마이징이 가능합니다.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
extends:
- recommended
apis:
core@v2:
root: ./openapi/openapi.yaml
rules:
no-ambiguous-paths: error
external@v1:
root: ./openapi/external.yaml
openapi:
hideLogo: true
openapi:
schemaExpansionLevel: 2
generateCodeSamples:
languages:
- lang: curl
- lang: Python
여러 OpenAPI 파일을 하나로 합치기
MSA 환경에서는 각 서비스별로 OpenAPI 파일을 관리하는 경우가 많습니다. Redocly는 여러 파일을 논리적으로 합쳐서 하나의 문서처럼 보여주는 강력한 기능을 제공합니다.
openapi.yaml 파일 내에서 $ref 키워드를 사용하여 다른 파일의 내용을 참조할 수 있습니다.
1
2
3
4
5
6
7
8
9
10
# openapi.yaml
openapi: 3.0.3
info:
title: Unified API Documentation
version: 1.0.0
paths:
/users/{userId}:
$ref: './users-api.yaml#/paths/~1users~1{userId}' # users-api.yaml 파일 참조
/products/{productId}:
$ref: './products-api.yaml#/paths/~1products~1{productId}' # products-api.yaml 파일 참조
redocly build-docs명령어를 실행하면 Redocly가 참조된 파일들을 모두 읽어와 하나의 완성된 HTML 파일로 만들 수 있습니다.
마치며
API를 직접 테스트하는 기능이 꼭 필요하다면 Swagger UI가 좋은 선택일 수 있지만, 검색도 되고, html로 공유하고 싶다면 Redocly도 좋은 선택지일 수 있습니다.
[출처]
- https://redocly.com/docs/cli/configuration
- https://github.com/Redocly/museum-openapi-example