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

API 문서를 생성할 도구를 선택할 때 라이선스도 결정 요인 중 하나입니다. 오픈 소스 생성기를 사용하면 코드를 읽고, 결과물을 직접 호스팅하고, 개발이 정체되면 포크할 수 있으며, 이미 출시한 기능에 대해 사용자 수 제한이나 유료화 장벽에 부딪힐 일이 없습니다. 모든 CI 빌드에서 실행되는 작업의 경우, 이는 결과물의 품질만큼이나 중요합니다.

이 목록은 명령줄에서 실행되는 API 문서 도구 중 오픈 소스만 모은 것입니다. 여기에 있는 모든 도구는 MIT 또는 Apache 2.0과 같은 실제 라이선스 하에 소스 코드가 공개되어 있으며, GitHub에서 호스팅되고, 계정 없이 무료로 실행할 수 있습니다. OpenAPI 또는 Swagger 파일을 가리키면 Markdown, 정적 HTML 페이지 또는 직접 소유하고 호스팅하는 전체 문서 사이트를 제공합니다.

각 도구의 정확한 라이선스와 자체 호스팅 가능 여부를 표시할 것입니다. 이것이 바로 일반적인 도구 소개가 아닌 오픈 소스 요약본을 읽는 주된 이유이기 때문입니다. 더 넓은 범위의 정보를 원한다면 최고의 REST API 문서 도구 요약본에서 GUI 플랫폼도 다룹니다. 아래 모든 도구가 읽는 형식은 OpenAPI Specification이므로, 유효한 스펙이 시작점입니다.

한 가지 솔직한 고백을 미리 하자면. Apidog는 거의 마지막에 등장하지만, 오픈 소스 항목은 아닙니다. 상업용 프리미엄 플랫폼입니다. 오픈 소스 도구들이 무엇을 다루고 다루지 않는지에 대한 비교를 정직하게 하기 위해 여기에 포함시켰을 뿐, 오픈 소스 옵션으로 포함한 것은 아닙니다.

버튼

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

오픈 소스는 단순히 "무료 다운로드"만을 의미하지 않습니다. 빌드에 연결할 문서 도구의 경우, 다음 세 가지가 도구가 진정으로 당신의 것인지 결정합니다.

진정한 라이선스. MIT 또는 Apache 2.0은 허락 없이 상업적으로 도구를 사용, 수정 및 재배포할 수 있음을 의미합니다. 둘 다 OSI 승인 라이선스입니다. Apache 2.0은 명시적인 특허 부여를 추가하여 일부 법무팀에서 선호합니다. 아래의 모든 도구는 이 두 라이선스 중 하나를 따릅니다.

자체 호스팅 가능한 결과물. 오픈 문서의 핵심은 어떤 것도 벤더의 서버에 의존하지 않는다는 것입니다. 이 도구들은 정적 파일을 생성합니다: 커밋하는 Markdown, 단일 HTML 페이지 또는 HTML/CSS/JS 폴더. GitHub Pages, S3 또는 일반 Nginx 서버에 호스팅하면, 도구 뒤의 프로젝트가 계속 작동하는지와 상관없이 작동합니다.

유지보수 및 커뮤니티. 소스 코드가 공개되어 있다는 것은 코드가 활발하게 유지보수될 때만 의미가 있습니다. 스타, 최근 커밋, 열린 이슈들은 필요한 경우 포크가 가능한지 여부를 알려줍니다. 여기에 있는 몇몇 도구는 보관되었지만 여전히 작동합니다. 해당 도구에 대해 명시하겠습니다.

오픈 소스 및 프리미엄 옵션 모두에서 비용이 들지 않는 관점을 다루는 글은 무료 API 문서 도구 목록입니다. 이제 도구들을 살펴보겠습니다.

Redocly CLI

Redocly CLI는 스펙을 세련되고 독립적인 HTML 참조 문서로 바꾸는 가장 빠른 방법입니다. MIT 라이선스를 따르며 오픈 코어 방식입니다: CLI와 그 아래 Redoc 렌더링 엔진은 GitHub에서 오픈 소스로 제공되며, 일부 호스팅 포털 기능은 Redocly의 유료 제품에 포함되어 있습니다. `build-docs` 명령어는 완전히 오픈 소스 부분에 속합니다.

npx @redocly/cli build-docs openapi.yaml -o api-docs.html

이는 Redoc을 기반으로 하는 하나의 HTML 파일을 생성합니다. 로컬에서 열거나, 어떤 정적 호스트에든 올리거나, 릴리스에 첨부할 수 있습니다. 외부와 통신하지 않으며, 패키지가 캐시되면 오프라인에서도 실행할 수 있습니다.

장점: 하나의 명령으로 MIT 라이선스 및 자체 호스팅 가능한 깔끔한 단일 페이지 API 참조 문서를 생성합니다. 한계점: 결과물이 단일 페이지이므로 다중 페이지 포털이 아닌 참조 문서이며, 더 풍부한 테마는 유료 등급에 있습니다. 렌더링 엔진들을 서로 비교하고 있다면, Redocly 대안 비교 글에서 오픈 소스의 경계가 어디에 있는지 설명합니다.

Widdershins

Widdershins는 MIT 라이선스 하의 순수한 변환 도구입니다. OpenAPI 3, Swagger 2 또는 AsyncAPI를 읽어 Markdown을 출력합니다. 이것이 모든 기능입니다. 결과물이 일반 Markdown이므로, 완전히 소유하게 됩니다: 커밋하고, 풀 리퀘스트에서 차이를 확인하거나, 이미 운영 중인 어떤 정적 사이트에도 공급할 수 있습니다.

npm install -g widdershins
widdershins openapi.yaml -o api-docs.md

Widdershins가 생성하는 Markdown은 Slate와 호환되어, 이 목록의 뒷부분에 나오는 사이트 생성기와 깔끔하게 연결됩니다. 유용한 플래그: `--omitHeader`는 프론트 매터(front-matter)를 제거하고, `--language_tabs`는 코드 샘플 언어를 선택합니다.

장점: 스펙 내용을 벤더 종속성 없이 버전 관리가 가능한 Markdown으로 가져옵니다. 한계점: Markdown만 제공합니다. 스타일링이나 렌더링된 사이트가 없으므로, Widdershins는 파이프라인의 절반일 뿐입니다. 다른 도구가 Markdown을 페이지로 변환해야 합니다.

OpenAPI Generator

OpenAPI Generator는 Apache 2.0 라이선스를 따르며 커뮤니티가 운영하고, 2018년에 Swagger Codegen에서 포크되었습니다. 클라이언트 SDK로 가장 잘 알려져 있지만, 문서 생성기도 제공합니다: `markdown` 생성기는 Markdown 폴더를 생성하고, `html2`는 단일 독립형 HTML 페이지를 생성합니다.

npm install -g @openapitools/openapi-generator-cli
openapi-generator-cli generate -g markdown -i openapi.yaml -o docs/
openapi-generator-cli generate -g html2 -i openapi.yaml -o docs-html/

Apache 2.0 라이선스와 특허 부여는 신중한 법무팀에게도 쉽게 승인될 수 있게 하며, 이 프로젝트는 이 분야에서 가장 활발하게 유지보수되는 프로젝트 중 하나입니다.

장점: 강력한 커뮤니티 지원을 받는 관대한 라이선스 하에 SDK와 문서 모두에 하나의 도구를 재사용할 수 있습니다. 한계점: npm 래퍼는 첫 실행 시 여전히 Java jar 파일을 다운로드하므로 단일 바이너리가 아니며, 템플릿화된 결과물은 평범합니다. 문서만 필요한 경우, 더 가벼운 변환 도구들이 존재합니다.

Swagger Codegen

Swagger Codegen은 Swagger 팀의 원본 템플릿 기반 생성기로, Apache 2.0 라이선스를 따릅니다. OpenAPI Generator 포크보다 먼저 나왔으며 SmartBear에서 여전히 유지보수하고 있습니다. 문서화에 있어서는 두 가지 경로를 제공합니다: 정적 단일 페이지 참조를 위한 `html`과 작은 대화형 사이트를 위한 `dynamic-html`.

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

두 프로젝트는 DNA와 많은 옵션을 공유하므로, 팀이 이미 Swagger 툴체인에 표준화되어 있다면 이 도구를 계속 사용할 수 있습니다.

장점: 이미 Swagger 생태계에 투자했으며, 스텁을 생성하는 동일한 Apache 2.0 도구로 문서를 만들고자 하는 팀에 적합합니다. 한계점: OpenAPI Generator와 마찬가지로 Java 기반이며, 커뮤니티 포크보다 개발 속도가 느립니다. 대부분의 새로운 설정에서는 OpenAPI Generator가 더 활발한 선택지이며, Swagger Codegen은 연속성 측면에서 우수합니다.

OpenAPI 플러그인을 사용한 Docusaurus

단일 HTML 페이지로는 부족하고 실제 버전 관리되는 문서 사이트를 원한다면, Docusaurus가 오픈 소스 기반입니다. Meta에서 구축한 MIT 라이선스 도구로, 웹에서 가장 널리 사용되는 정적 사이트 생성기 중 하나입니다. 그 자체로 Markdown과 MDX를 렌더링하며, Palo Alto Networks에서 유지보수하는 MIT 라이선스 docusaurus-openapi-docs 플러그인은 스펙으로부터 문서를 생성하는 기능을 추가합니다.

npx create-docusaurus@latest my-docs classic
npm install docusaurus-plugin-openapi-docs docusaurus-theme-openapi-docs
npm run docusaurus gen-api-docs all

스펙 경로로 플러그인을 구성한 후, `gen-api-docs`는 OpenAPI 파일을 Docusaurus 사이트 내에서 렌더링되는 MDX 페이지로 변환하며, "직접 사용해보기" 패널과 사이드바 탐색 기능을 포함합니다.

장점: 버전 관리, 검색, 그리고 생성된 참조 문서와 함께 수동으로 작성된 가이드를 포함하는 완전한 자체 호스팅 문서 포털을 제공합니다. 한계점: 여기 소개된 도구 중 가장 무거운 설정입니다. React 사이트와 빌드 단계를 설정해야 하므로, 참조 페이지 하나만 필요하다면 과할 수 있습니다. 그 경우에는 Redocly CLI가 더 짧은 경로입니다.

Slate

Slate는 왼쪽에 탐색, 중앙에 설명, 오른쪽에 코드 샘플이 있는 고전적인 세 열 API 문서 레이아웃으로, 모두 정적 사이트로 렌더링됩니다. Apache 2.0 라이선스를 따르며 Middleman 기반이므로 Ruby 툴체인이 필요합니다. 위 변환 도구들과 달리 Slate는 OpenAPI를 직접 읽지 않습니다. 당신이 Markdown을 작성하면 Slate가 렌더링합니다.

# after cloning your Slate fork and running bundle install
bundle exec middleman build

이는 완전한 정적 사이트를 `build/` 폴더에 생성하며, 이 폴더는 어디든 호스팅할 수 있습니다. 여기서 Widdershins가 빛을 발합니다: 스펙을 Markdown으로 변환한 다음, Slate가 이를 인지 가능한 레이아웃으로 렌더링하도록 합니다.

장점: 완전히 자체 호스팅되는 정적 사이트에서 구조와 문구에 대한 편집 통제권을 원하는 수동으로 큐레이팅된 서술형 문서에 적합합니다. 한계점: 원본 저장소는 보관되었지만(유지보수자가 물러났지만) 여전히 빌드되고 포크는 활발하며, Ruby 의존성은 `npx` 한 줄 명령어보다 더 무겁습니다. 문서가 스펙에서 직접 재생성된다면, 변환 도구가 더 가볍습니다.

Apidog CLI (솔직한 비고, 오픈 소스 항목 아님)

위에 언급된 도구들은 모두 오픈 소스이며, 각각 변환, 렌더링, 또는 정적 파일 호스팅 중 한 가지 기능을 다룹니다. 이들이 남기는 공백은 라이브 프로젝트입니다. API가 단독 YAML 파일이 아니라 엔드포인트, 스키마, 예제를 포함하는 유지보수되는 프로젝트라면, 수동으로 변환 도구, 렌더러, 호스트를 연결하고 이 세 가지를 모두 동기화해야 합니다.

이것이 바로 `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

한 번의 내보내기로 프로젝트를 빌드 파이프라인 없이 Markdown 또는 HTML로 변환할 수 있으며, `apidog doc` 및 `apidog docs-site`는 스크립트에서 문서 리소스를 관리합니다. 출력은 구조화된 JSON이므로 CI나 에이전트로 깔끔하게 연결됩니다. Apidog CLI 완벽 가이드는 인증 및 각 명령어 그룹을 설명합니다. Markdown 내보내기 워크플로우를 원한다면, Markdown 내보내기 기능을 갖춘 API 문서 생성기 글에서 더 자세히 다룹니다.

경계는 다음과 같습니다: 오픈 소스 도구는 당신이 소유하는 코드, 직접 호스팅하는 파일, 그리고 벤더 종속성이 없음을 제공합니다. Apidog는 유지보수되는 프로젝트에서 공유 가능한 문서로 이어지는 통합된 경로를 제공하지만, 호스팅되는 프리미엄 제품이라는 대가가 따릅니다. 진실의 원천이 정적 스펙인지 또는 라이브 프로젝트인지에 따라 선택하세요.

선택 방법

팀이 소유해야 할 내용에 맞춰 라이선스와 결과물을 선택하세요.

도구	최적 용도	설치	오픈 소스?	결과물
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	수동으로 큐레이팅된 세 열 문서	Ruby + Bundler	예 (Apache 2.0)	정적 사이트
Apidog CLI	라이브 프로젝트에서 내보내기	`npm i -g apidog-cli`	아니오 (프리미엄)	Markdown 또는 HTML

요약하자면: 단순 스펙과 공유 가능한 HTML 참조 문서에는 Redocly CLI를 사용하세요. 버전 관리하는 Markdown을 원한다면 Widdershins를 사용하세요. 이미 SDK를 생성하고 있다면 OpenAPI Generator도 문서를 생성하며, Swagger에 표준화되어 있다면 Swagger Codegen이 적합합니다. 버전 관리 및 가이드가 포함된 실제 포털을 원한다면 Docusaurus와 OpenAPI 플러그인이 오픈 소스 기반이며, 수동으로 작성하고 편집 제어가 필요한 문서에는 Slate가 선택됩니다. 이 모든 도구는 소스 코드가 공개되어 있고 자체 호스팅이 가능하므로, 당신이 출시하는 어떤 것도 벤더의 지속적인 운영에 의존하지 않습니다. 더 넓은 범위의 무료 옵션을 보려면 무료 API 문서 도구 요약본에서 오픈 소스 및 프리미엄 옵션을 함께 다룹니다.

마무리하며

오픈 소스 문서 CLI를 선택하는 것은 라이선스, 결과물, 그리고 문서가 어디에 위치하는지에 달려 있습니다. MIT와 Apache 2.0 모두 사용자 비용 없이 사용, 수정 및 자체 호스팅을 허용하므로, 필요한 결과물을 생성하는 가장 작은 도구를 선택하세요: 단일 페이지에는 Redocly CLI, Markdown에는 Widdershins, SDK와 함께 문서를 생성하려면 OpenAPI Generator 또는 Swagger Codegen, 포털용으로는 Docusaurus, 수동으로 큐레이팅된 페이지에는 Slate를 선택하세요.

API가 단독 파일이 아닌 유지보수되는 프로젝트에 속하고, 세 가지 도구를 연결하는 대신 문서를 내보내고 싶다면, Apidog를 다운로드하여 프로젝트에 `apidog export`를 시도해보세요. 이는 CI 작업에 통합되어 API가 변경될 때마다 문서가 다시 빌드되지만, 이것이 오픈 소스 바이너리가 아닌 프리미엄 플랫폼이라는 점을 명확히 인지하세요.