DEV Community

Cover image for API 문서화용 경량 CLI 도구 베스트
Rihpig
Rihpig

Posted on • Originally published at apidog.com

API 문서화용 경량 CLI 도구 베스트

OpenAPI 파일에서 문서를 생성하려고 할 때, 서비스를 구축하거나 포털에 로그인하거나 npm 패키지를 대량으로 추가하고 싶지는 않을 것입니다. 사양을 읽어 마크다운 파일 또는 어디서든 호스팅할 수 있는 단일 HTML 페이지를 생성하는 명령 하나면 충분합니다.

지금 Apidog를 사용해 보세요

이 글은 바로 그 목적에 맞는 도구를 정리합니다. 모두 단일 바이너리, npx 한 줄 명령 또는 한 번 설치하면 되는 패키지입니다. 빠르게 시작할 수 있고, 구성이 거의 필요 없으며, 완전한 플랫폼을 설치하지 않아도 문서 생성 작업을 수행합니다.

일부 도구는 기존 문서 사이트에 넣을 수 있는 마크다운을 생성합니다. 일부는 독립형 HTML 파일을 생성합니다. 모두 터미널과 CI에서 실행할 수 있다는 점이 핵심입니다.

더 넓은 범위의 문서화 플랫폼이 필요하다면 최고의 REST API 문서화 도구에서 GUI 중심 도구를 확인하세요. 이 글은 터미널 우선, 낮은 설치 공간을 가진 도구에 집중합니다. 각 도구가 읽는 입력 형식은 OpenAPI Specification입니다.

API 문서화를 위한 CLI 도구가 “경량”이라는 것은 무엇을 의미하는가

경량은 기능이 부족하다는 뜻이 아닙니다. 설치 공간과 실행 마찰이 작다는 뜻입니다. 다음 네 가지 기준으로 판단할 수 있습니다.

설치 크기와 의존성

단일 바이너리 또는 npm 패키지 하나가 프레임워크 전체보다 가볍습니다. 문서 페이지 하나를 만들기 위해 언어 런타임, 번들러, 플러그인 시스템까지 설치해야 한다면 경량 도구라고 보기 어렵습니다.

시작과 구성

가장 좋은 도구는 사양 파일을 읽고 별도 설정 없이 결과물을 생성합니다. openapi.yaml을 전달하면 파일이 생성되는 방식입니다. 실행 전에 구성 파일이 필요한 도구는 이 기준에서 불리합니다.

단일 목적 출력

아래 도구들은 모두 한 가지 작업에 집중합니다.

OpenAPI 사양 입력 → 문서 출력
Enter fullscreen mode Exit fullscreen mode

출력은 마크다운 또는 HTML입니다. 불필요한 서버나 플랫폼 기능을 추가하지 않기 때문에 파이프라인에서 빠르고 예측 가능하게 동작합니다.

어디서든 실행 가능

GUI, 공개 도구 사용을 위한 로그인, 유지할 서버가 필요하지 않아야 합니다. 로컬 노트북과 CI 작업에서 같은 명령으로 실행할 수 있어야 합니다. 더 많은 무료 플랫폼 옵션은 무료 API 문서화 도구 목록에서 확인할 수 있습니다.

이제 가장 작은 도구부터 살펴보겠습니다.

Widdershins

Widdershins는 이 목록에서 가장 작은 도구입니다. OpenAPI 3, Swagger 2 또는 AsyncAPI 파일을 마크다운으로 변환하는 단일 npm 패키지입니다. 서버를 실행하거나 문서 사이트를 렌더링하지 않고 .md 파일만 생성합니다.

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

생성된 마크다운은 Slate와 호환됩니다. 이후 정적 문서 사이트에 넣을 계획이라면 유용합니다.

자주 사용하는 옵션은 다음과 같습니다.

# YAML 프론트매터 제거
widdershins openapi.yaml -o api-docs.md --omitHeader

# 표시할 코드 샘플 언어 지정
widdershins openapi.yaml -o api-docs.md --language_tabs 'shell:Shell' 'javascript:JavaScript'
Enter fullscreen mode Exit fullscreen mode

적합한 경우

  • 사양 내용을 커밋 가능한 마크다운으로 변환해야 할 때
  • 생성 결과를 Git diff로 검토해야 할 때
  • 다른 문서 시스템의 입력으로 사용할 마크다운이 필요할 때

한계

  • 출력은 마크다운뿐입니다.
  • 스타일링, 대화형 “직접 해보기” 패널, 호스팅 기능은 없습니다.
  • 마크다운을 실제 사이트로 렌더링하려면 별도 도구가 필요합니다.

Widdershins는 렌더러가 아니라 변환기입니다.

OpenAPI Generator (문서 생성기)

OpenAPI Generator는 클라이언트 SDK 생성기로 잘 알려져 있지만, 문서 생성기도 제공합니다. 사양 파일만 있을 때 마크다운 또는 HTML 문서를 만들 수 있습니다.

  • markdown: 마크다운 파일 폴더 생성
  • html2: 자체 포함된 단일 HTML 페이지 생성

npm 래퍼를 사용하면 직접 Java 명령을 실행하지 않아도 됩니다.

npm install -g @openapitools/openapi-generator-cli

# 마크다운 문서 생성
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/

# 단일 HTML 문서 생성
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/
Enter fullscreen mode Exit fullscreen mode

npm 래퍼는 내부적으로 JDK 기반 jar 파일을 다운로드합니다. 따라서 첫 실행은 Widdershins보다 무겁지만, 이후에는 동일한 명령으로 반복 생성할 수 있습니다.

적합한 경우

  • 이미 OpenAPI Generator로 SDK를 생성하고 있을 때
  • SDK와 문서 생성을 같은 도구로 통일하고 싶을 때
  • 마크다운과 독립형 HTML 중 선택해야 할 때

한계

  • 출력은 기본 템플릿 중심이며 비교적 단순합니다.
  • 첫 실행 시 jar 파일을 다운로드합니다.
  • 문서 생성만 필요하다면 더 가벼운 선택지가 있습니다.

Redocly CLI (build-docs)

단일 명령으로 보기 좋은 독립형 HTML 문서를 만들고 싶다면 Redocly CLI의 build-docs 명령이 빠른 선택입니다. Redoc 기반 문서를 하나의 자체 포함 HTML 파일로 생성합니다.

npx @redocly/cli build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

기본 출력 파일은 redoc-static.html입니다. 파일명을 지정하려면 --output을 사용하세요.

npx @redocly/cli build-docs openapi.yaml --output api.html
Enter fullscreen mode Exit fullscreen mode

npx로 실행할 수 있으므로 전역 설치 없이 바로 테스트할 수 있습니다.

CI에서는 다음처럼 사용할 수 있습니다.

npx @redocly/cli build-docs openapi.yaml --output public/api.html
Enter fullscreen mode Exit fullscreen mode

적합한 경우

  • 세련된 기본 테마의 API 참조 문서가 필요할 때
  • 공유하거나 이메일로 전달할 단일 HTML 파일이 필요할 때
  • 정적 호스트에 바로 배포할 결과물이 필요할 때

한계

  • 결과물은 여러 페이지 문서 포털이 아니라 하나의 HTML 참조 페이지입니다.
  • 더 풍부한 테마와 미리보기 기능은 Redocly 유료 등급에 포함됩니다.

유사한 렌더러와 비교하려면 Redocly 대안 및 Scalar 대안 비교를 참고하세요.

Slate

Slate는 앞선 도구와 성격이 다릅니다. OpenAPI 사양을 문서로 변환하는 도구가 아니라, 수기로 작성한 API 문서를 정적 사이트로 빌드하는 생성기입니다.

마크다운을 작성하면 Slate가 다음과 같은 고전적인 3열 문서 레이아웃을 제공합니다.

  • 탐색 메뉴
  • 본문 콘텐츠
  • 코드 샘플

Slate는 Middleman 기반이므로 Ruby가 필요합니다.

# Slate 저장소를 클론하고 의존성을 설치한 뒤 실행
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

빌드 결과는 build/ 폴더에 생성되며, 정적 파일 호스팅이 가능한 곳이라면 어디에나 배포할 수 있습니다.

Widdershins와 조합하면 다음 워크플로우를 구성할 수 있습니다.

# 1. OpenAPI 사양을 마크다운으로 변환
widdershins openapi.yaml -o source/index.html.md

# 2. Slate 정적 사이트 빌드
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

적합한 경우

  • 서술형 문서를 직접 편집하고 싶을 때
  • 문서 구조와 문체를 세밀하게 제어해야 할 때
  • 고정된 문서 사이트 레이아웃이 필요할 때

한계

  • Ruby 툴체인이 필요합니다.
  • 자체적으로 OpenAPI 파일을 읽지 않습니다.
  • 사양 기반 문서만 자동 생성하려는 경우에는 변환기와 렌더러를 조합해야 합니다.

Apidog CLI (내보내기 + 문서)

앞선 오픈 도구는 변환, 렌더링, 호스팅 중 하나의 역할에 집중합니다. 하지만 API가 단일 YAML 파일이 아니라 이미 프로젝트 안에서 관리되고 있다면 여러 도구를 연결하는 작업이 번거로울 수 있습니다.

이 경우 apidog-cli를 사용할 수 있습니다. Apidog의 명령줄 도구로, 프로젝트를 빌드 파이프라인 없이 마크다운 또는 HTML로 내보낼 수 있습니다.

먼저 npm으로 설치하고 토큰으로 인증합니다.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
Enter fullscreen mode Exit fullscreen mode

프로젝트 문서를 마크다운 또는 HTML로 내보냅니다.

apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html
Enter fullscreen mode Exit fullscreen mode

문서 리소스와 문서 사이트도 CLI에서 관리할 수 있습니다.

# 프로젝트 문서 조회
apidog doc list --project <projectId>

# 게시된 문서 사이트 조회
apidog docs-site list --project <projectId>
Enter fullscreen mode Exit fullscreen mode

출력은 구조화된 JSON이므로 다른 스크립트 단계에 전달하거나 자동화 작업에서 처리하기 쉽습니다. 명령별 사용법은 Apidog CLI 전체 가이드에서 확인할 수 있습니다.

적합한 경우

  • API가 이미 관리형 Apidog 프로젝트에 존재할 때
  • 프로젝트에서 마크다운 또는 HTML을 바로 내보내야 할 때
  • 스크립트나 CI에서 문서 생성과 문서 사이트 관리를 함께 처리할 때

한계

  • Apidog는 오픈 소스가 아니며, CLI는 호스팅된 프로젝트와 통신합니다.
  • OpenAPI 린트나 스타일 가이드 강제는 담당하지 않습니다.
  • 린트와 규칙 검증은 Redocly 또는 Spectral 같은 도구가 더 적합합니다.

Apidog CLI는 변환기, 렌더러, 호스팅 도구를 직접 연결하는 대신 관리되는 API 프로젝트에서 공유 가능한 문서로 내보내는 통합 경로를 제공합니다. 마크다운 내보내기에 집중하고 싶다면 마크다운 내보내기 기능을 갖춘 API 문서 생성기를 참고하세요.

선택 방법

입력 형태와 필요한 출력에 따라 선택하세요.

도구 적합한 용도 설치 오픈 소스? 출력
Widdershins 사양을 마크다운으로 빠르게 변환 npm i -g widdershins 예 (MIT) 마크다운
OpenAPI Generator SDK와 함께 문서 생성 npm i -g @openapitools/openapi-generator-cli 예 (Apache 2.0) 마크다운 또는 HTML
Redocly CLI 하나의 세련된 HTML 페이지 npx @redocly/cli 예 (MIT, 오픈 코어) 독립형 HTML
Slate 수작업으로 선별된 문서 사이트 Ruby + Bundler 예 (Apache 2.0) 정적 사이트
Apidog CLI 라이브 프로젝트에서 내보내기 npm i -g apidog-cli 아니요 (무료 티어) 마크다운 또는 HTML

빠르게 결정하려면 다음 기준을 사용하세요.

OpenAPI 파일 → 커밋 가능한 마크다운
  → Widdershins

OpenAPI 파일 → 공유 가능한 단일 HTML
  → Redocly CLI build-docs

SDK와 문서를 함께 생성
  → OpenAPI Generator

수작업으로 작성하는 문서 사이트
  → Slate

관리형 API 프로젝트 → 문서 내보내기 및 사이트 관리
  → Apidog CLI
Enter fullscreen mode Exit fullscreen mode

전반적인 무료 옵션이 필요하다면 무료 API 문서화 도구 요약도 참고할 수 있습니다.

마무리

경량 API 문서화 도구를 선택하는 기준은 단순합니다. 필요한 출력을 만드는 가장 작은 도구를 선택하세요.

  • 사양에서 마크다운을 생성하려면 Widdershins
  • 단일 HTML 참조 문서를 생성하려면 redocly build-docs
  • 이미 SDK를 생성 중이라면 OpenAPI Generator
  • 문서를 직접 작성해야 한다면 Slate
  • API가 실제 프로젝트로 관리되고 있다면 apidog-cli export

API가 단일 파일이 아니라 프로젝트에 존재한다면 Apidog를 다운로드한 뒤 apidog export를 실행해 보세요. CI 작업에 추가하면 API 변경 시 문서를 다시 생성하는 흐름을 구성할 수 있습니다.

Top comments (0)