DEV Community

Cover image for 무료 오픈소스 API 문서화 CLI 도구
Rihpig
Rihpig

Posted on • Originally published at apidog.com

무료 오픈소스 API 문서화 CLI 도구

API 문서 생성 도구를 선택할 때는 기능뿐 아니라 라이선스도 확인해야 합니다. 오픈 소스 생성기는 소스 코드를 검토하고, 결과물을 직접 호스팅하며, 개발이 중단되면 포크할 수 있습니다. 또한 이미 배포한 기능에 사용자 수 제한이나 유료화 장벽이 추가될 위험도 줄어듭니다. 모든 CI 빌드에서 실행할 문서 생성 작업이라면 결과물의 품질만큼 소유권과 재현 가능성이 중요합니다.

지금 Apidog 사용해 보기

이 글은 명령줄에서 실행할 수 있는 오픈 소스 API 문서 도구만 정리합니다. 각 도구는 MIT 또는 Apache 2.0 같은 라이선스로 소스 코드가 공개되어 있으며, GitHub에서 호스팅되고 계정 없이 실행할 수 있습니다. OpenAPI 또는 Swagger 파일을 입력으로 받아 Markdown, 정적 HTML 또는 직접 소유·호스팅할 수 있는 문서 사이트를 생성합니다.

각 도구의 라이선스와 자체 호스팅 가능 여부를 함께 확인합니다. GUI 플랫폼까지 포함한 더 넓은 비교가 필요하다면 최고의 REST API 문서 도구를 참고하세요. 아래 도구들이 주로 읽는 형식은 OpenAPI Specification이므로, 먼저 유효한 OpenAPI 스펙을 준비해야 합니다.

참고: Apidog는 글 후반부에 비교 대상으로 등장하지만 오픈 소스 도구가 아닙니다. 호스팅형 상업용 프리미엄 플랫폼이며, 오픈 소스 도구가 해결하는 범위와 해결하지 않는 범위를 명확히 비교하기 위해 포함했습니다.

CLI 문서 도구가 “오픈 소스”가 되려면?

“무료 다운로드”만으로는 오픈 소스라고 보기 어렵습니다. CI에 연결할 문서 생성 도구라면 다음 세 가지를 확인하세요.

  1. 실제 오픈 소스 라이선스

    MIT와 Apache 2.0은 상업적 사용, 수정, 재배포를 허용하는 OSI 승인 라이선스입니다. Apache 2.0은 명시적인 특허 부여 조항이 있어 법무 검토에서 선호되기도 합니다.

  2. 자체 호스팅 가능한 결과물

    벤더 서버가 아니라 정적 파일을 생성해야 합니다. Markdown, 단일 HTML 파일 또는 HTML/CSS/JS 폴더를 생성한다면 GitHub Pages, S3, Nginx 등 원하는 환경에 배포할 수 있습니다.

  3. 유지보수 상태와 커뮤니티

    라이선스가 열려 있어도 유지보수가 멈췄다면 운영 비용이 커질 수 있습니다. 최근 커밋, 이슈, 릴리스, 포크 활동을 확인하세요. 보관된 프로젝트라도 정상적으로 빌드되고 활발한 포크가 있다면 사용할 수 있지만, 이를 의식적으로 선택해야 합니다.

오픈 소스와 프리미엄 옵션을 함께 비교하려면 무료 API 문서 도구 목록도 참고할 수 있습니다.

Redocly CLI

Redocly CLI는 OpenAPI 스펙을 세련된 독립형 HTML 참조 문서로 빠르게 변환합니다. MIT 라이선스 기반의 오픈 코어 모델이며, CLI와 Redoc 렌더링 엔진은 오픈 소스입니다. 일부 호스팅 포털 기능만 Redocly 유료 제품에 포함됩니다.

빠르게 HTML 문서 생성하기 

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

생성된 api-docs.html은 다음처럼 바로 사용할 수 있습니다.

  • 로컬 브라우저에서 열기
  • GitHub Pages 또는 S3에 업로드
  • 릴리스 산출물에 첨부
  • CI에서 생성 후 정적 서버에 배포

패키지가 캐시된 상태라면 오프라인에서도 실행할 수 있습니다.

Redocly CLI 문서 예시

적합한 경우

  • 단일 HTML API 참조 문서가 필요할 때
  • 별도 서버나 포털 없이 빠르게 배포하고 싶을 때
  • CI 결과물로 문서 파일 하나를 관리하고 싶을 때

한계

  • 결과물은 다중 페이지 포털이 아닌 단일 페이지입니다.
  • 더 풍부한 테마와 포털 기능은 유료 제품 범위에 포함됩니다.

렌더링 엔진을 비교하려면 Redocly 대안도 참고하세요.

Widdershins

Widdershins는 OpenAPI 3, Swagger 2, AsyncAPI를 Markdown으로 변환하는 MIT 라이선스 도구입니다. 렌더링 사이트가 아니라 변환에 집중하므로, 생성된 Markdown을 Git으로 관리하거나 다른 정적 사이트 생성기에 전달하기 좋습니다.

OpenAPI를 Markdown으로 변환하기 

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

생성된 api-docs.md를 저장소에 커밋하면 API 변경에 따른 문서 차이를 풀 리퀘스트에서 확인할 수 있습니다.

자주 쓰는 옵션 

# front matter 제거
widdershins openapi.yaml --omitHeader -o api-docs.md

# 코드 샘플 언어 지정
widdershins openapi.yaml \
  --language_tabs 'javascript:JavaScript' 'python:Python' \
  -o api-docs.md
Enter fullscreen mode Exit fullscreen mode

Widdershins 출력은 Slate와 호환되므로, Markdown 생성과 문서 사이트 렌더링을 분리한 파이프라인을 구성할 수 있습니다.

Widdershins 문서 출력 예시

적합한 경우

  • 스펙을 버전 관리 가능한 Markdown으로 변환하고 싶을 때
  • 기존 문서 사이트나 정적 사이트 생성기에 문서를 연결할 때
  • 문서 텍스트와 구조를 직접 편집하고 싶을 때

한계

  • Markdown만 생성합니다.
  • 스타일링과 사이트 렌더링은 별도 도구가 필요합니다.

OpenAPI Generator

OpenAPI Generator는 Apache 2.0 라이선스의 커뮤니티 프로젝트입니다. 2018년 Swagger Codegen에서 포크되었으며, 클라이언트 SDK 생성기로 잘 알려져 있지만 Markdown과 HTML 문서 생성도 지원합니다.

Markdown 또는 HTML 생성하기 

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

# Markdown 폴더 생성
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

SDK와 문서를 동일한 스펙, 동일한 생성기, 동일한 CI 작업에서 만들 수 있다는 점이 핵심입니다.

예를 들어 CI에서는 다음과 같이 구성할 수 있습니다.

openapi-generator-cli generate -g typescript-fetch -i openapi.yaml -o sdk/
openapi-generator-cli generate -g html2 -i openapi.yaml -o public/docs/
Enter fullscreen mode Exit fullscreen mode

OpenAPI Generator 예시

적합한 경우

  • SDK와 문서를 한 도구로 생성할 때
  • Apache 2.0 라이선스와 특허 부여 조항이 필요한 조직
  • 활발한 커뮤니티와 다양한 생성 템플릿이 필요한 경우

한계

  • npm 래퍼는 최초 실행 시 Java JAR 파일을 다운로드합니다.
  • 문서만 필요하다면 더 가벼운 변환 도구가 단순할 수 있습니다.
  • 기본 템플릿 결과물은 비교적 평범할 수 있습니다.

Swagger Codegen

Swagger Codegen은 Swagger 팀의 원본 템플릿 기반 생성기이며 Apache 2.0 라이선스를 따릅니다. SmartBear에서 유지보수하고 있으며, 정적 참조 문서용 html과 작은 대화형 문서 사이트용 dynamic-html을 제공합니다.

HTML 문서 생성하기 

npm install -g swagger-codegen-cli
swagger-codegen-cli generate -i openapi.yaml -l html -o docs/
Enter fullscreen mode Exit fullscreen mode

팀이 이미 Swagger Codegen으로 서버 스텁이나 SDK를 생성하고 있다면 문서 생성도 같은 툴체인에 포함할 수 있습니다.

Swagger Codegen 예시

적합한 경우

  • Swagger Codegen 중심으로 표준화된 기존 팀
  • SDK, 서버 스텁, 문서를 같은 도구로 생성하려는 경우
  • 기존 생성 설정을 유지해야 하는 경우

한계

  • Java 기반 도구입니다.
  • 새 프로젝트에서는 커뮤니티 포크인 OpenAPI Generator가 더 활발한 선택지일 수 있습니다.
  • Swagger Codegen은 새 도입보다 기존 환경의 연속성에 더 적합합니다.

Docusaurus + OpenAPI 플러그인

단일 HTML 파일보다 완전한 문서 포털이 필요하다면 Docusaurus를 기반으로 구성할 수 있습니다. Docusaurus는 Meta가 만든 MIT 라이선스 정적 사이트 생성기이며 Markdown과 MDX를 렌더링합니다.

Palo Alto Networks의 docusaurus-openapi-docs 플러그인을 추가하면 OpenAPI 스펙을 Docusaurus 페이지로 생성할 수 있습니다.

프로젝트 생성 및 플러그인 설치 

npx create-docusaurus@latest my-docs classic
cd my-docs

npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all
Enter fullscreen mode Exit fullscreen mode

이후 OpenAPI 파일 경로를 플러그인 설정에 추가합니다. gen-api-docs 명령은 스펙을 MDX 페이지로 변환하고, 생성된 문서는 Docusaurus 사이드바와 탐색 구조에 통합됩니다.

추천 구성

  • 사람이 작성하는 가이드: docs/
  • OpenAPI에서 생성하는 참조 문서: docs/api/
  • API 버전별 스펙: openapi/v1.yaml, openapi/v2.yaml
  • CI 단계: 스펙 검증 → API 문서 생성 → 정적 사이트 빌드 → 배포

Docusaurus OpenAPI 문서 예시

적합한 경우

  • API 참조 문서와 사용 가이드를 하나의 포털에서 제공할 때
  • 검색, 버전 관리, 사이드바 탐색이 필요할 때
  • 문서를 정적 사이트로 자체 호스팅할 때

한계

  • 이 글의 도구 중 설정이 가장 무겁습니다.
  • React 기반 사이트와 빌드 파이프라인을 관리해야 합니다.
  • 참조 페이지 하나만 필요하다면 Redocly CLI가 더 간단합니다.

Slate

Slate는 왼쪽 탐색, 중앙 설명, 오른쪽 코드 샘플로 구성된 전형적인 3열 API 문서 레이아웃을 제공합니다. Apache 2.0 라이선스이며 Middleman 기반이므로 Ruby 툴체인이 필요합니다.

Slate는 OpenAPI를 직접 읽지 않습니다. Markdown을 직접 작성하거나 Widdershins로 생성한 Markdown을 전달한 뒤 Slate가 사이트를 렌더링하는 방식입니다.

정적 사이트 빌드하기 

# Slate 저장소를 포크하고 bundle install을 실행한 뒤
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

빌드 결과는 build/ 폴더에 생성됩니다. 이 폴더를 GitHub Pages, S3, Nginx 등 원하는 정적 호스팅 환경에 배포하면 됩니다.

Widdershins와 연결하기 

widdershins openapi.yaml -o source/index.html.md
bundle exec middleman build
Enter fullscreen mode Exit fullscreen mode

이 방식은 스펙에서 초안을 생성한 뒤, 팀이 Markdown에서 설명·예제·표현을 직접 다듬고 싶을 때 유용합니다.

적합한 경우

  • 서술형 문서와 코드 샘플을 세밀하게 편집할 때
  • 전통적인 3열 API 문서 UI가 필요할 때
  • 모든 결과물을 정적 사이트로 직접 호스팅할 때

한계

  • 원본 저장소는 보관되었지만 여전히 빌드할 수 있고 포크가 활용됩니다.
  • Ruby와 Bundler 의존성은 npx 기반 도구보다 무겁습니다.
  • OpenAPI에서 자동 재생성만 할 목적이라면 전용 변환 도구가 더 가볍습니다.

Apidog CLI: 오픈 소스가 아닌 비교 대상

앞서 소개한 도구들은 변환, 렌더링, 정적 호스팅 중 하나 또는 일부에 집중합니다. 반면 API가 단일 YAML 파일이 아니라 엔드포인트, 스키마, 예제, 변경 이력을 포함한 유지보수 대상 프로젝트라면 변환기·렌더러·호스팅을 별도로 연결하고 동기화해야 합니다.

Apidog CLI 예시

apidog-cli는 이 워크플로우를 위한 비교 대상입니다. 다만 라이선스 경계는 명확합니다. Apidog는 오픈 소스가 아니라 무료 등급을 제공하는 호스팅형 상업용 프리미엄 플랫폼입니다. CLI는 로컬 스펙만 처리하는 방식이 아니라 호스팅된 프로젝트와 통신합니다.

프로젝트 문서 내보내기 

npm install -g apidog-cli

apidog login --with-token <YOUR_TOKEN>

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

apidog doc 및 apidog docs-site 명령은 스크립트에서 문서 리소스를 관리하는 데 사용할 수 있습니다. 출력은 구조화된 JSON이므로 CI나 자동화 에이전트에 연결할 수 있습니다.

인증과 명령어 그룹은 Apidog CLI 완벽 가이드에서 확인할 수 있습니다. Markdown 내보내기 흐름은 Markdown 내보내기 기능을 갖춘 API 문서 생성기에서 더 자세히 다룹니다.

선택 기준은 다음과 같습니다.

  • 오픈 소스 도구: 직접 소유하는 코드, 자체 호스팅하는 파일, 벤더 종속성 최소화
  • Apidog: 유지보수되는 프로젝트에서 공유 가능한 문서로 이어지는 통합된 흐름

진실의 원천이 정적 OpenAPI 파일인지, 호스팅된 라이브 프로젝트인지에 따라 선택하세요.

선택 방법

팀이 소유해야 하는 범위와 원하는 결과물에 따라 선택하면 됩니다.

도구 최적 용도 설치 오픈 소스? 결과물
Redocly CLI 세련된 HTML 단일 페이지 npx @redocly/cli 예 (MIT, 오픈 코어) 독립형 HTML
Widdershins 커밋 가능한 스펙 Markdown npm i -g widdershins 예 (MIT) Markdown
OpenAPI Generator 문서 및 SDK를 위한 하나의 도구 npm i -g @openapitools/openapi-generator-cli 예 (Apache 2.0) Markdown 또는 HTML
Swagger Codegen Swagger 표준화 팀 npm i -g swagger-codegen-cli 예 (Apache 2.0) HTML
Docusaurus + OpenAPI 플러그인 완전한 자체 호스팅 문서 사이트 npx create-docusaurus 예 (MIT) 정적 사이트
Slate 수동으로 큐레이팅한 3열 문서 Ruby + Bundler 예 (Apache 2.0) 정적 사이트
Apidog CLI 라이브 프로젝트에서 문서 내보내기 npm i -g apidog-cli 아니오 (프리미엄) Markdown 또는 HTML

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

  • 스펙 하나를 HTML 참조 문서로 배포: Redocly CLI
  • Git에서 관리할 Markdown 생성: Widdershins
  • SDK와 문서를 함께 생성: OpenAPI Generator
  • 기존 Swagger Codegen 환경 유지: Swagger Codegen
  • 가이드, 검색, 버전 관리를 포함한 문서 포털 구축: Docusaurus + OpenAPI 플러그인
  • 문서 문구와 레이아웃을 직접 큐레이션: Slate
  • 호스팅된 API 프로젝트에서 문서를 내보내기: Apidog CLI

모든 오픈 소스 옵션은 소스 코드가 공개되어 있고 결과물을 자체 호스팅할 수 있으므로, 배포한 문서가 특정 벤더의 지속적인 운영에 의존하지 않습니다. 더 넓은 무료 옵션 비교는 무료 API 문서 도구에서 확인할 수 있습니다.

마무리하며

오픈 소스 문서 CLI는 라이선스, 결과물 형식, 문서의 위치를 기준으로 선택하세요. MIT와 Apache 2.0은 모두 비용 없이 사용·수정·자체 호스팅을 허용하므로, 필요한 결과물을 만드는 가장 작은 도구부터 선택하는 것이 좋습니다.

  • 단일 페이지 HTML: Redocly CLI
  • Markdown: Widdershins
  • SDK와 함께 문서 생성: OpenAPI Generator 또는 Swagger Codegen
  • 문서 포털: Docusaurus
  • 수동으로 큐레이션한 페이지: Slate

API가 단일 파일이 아니라 유지보수되는 프로젝트에 속해 있고, 여러 도구를 연결하는 대신 문서를 바로 내보내고 싶다면 Apidog를 다운로드한 뒤 프로젝트에서 apidog export를 실행할 수 있습니다. API 변경 시 문서를 다시 빌드하도록 CI에 통합할 수 있지만, 이는 오픈 소스 바이너리가 아닌 프리미엄 플랫폼이라는 점은 분명히 구분해야 합니다.

Top comments (0)