OpenAPI 파일이 있고 거기서 문서를 얻고 싶을 때. 서비스를 구축하거나, 포털에 로그인하거나, npm의 절반을 가져오는 빌드 단계를 추가하고 싶지 않을 것입니다. 사양을 읽고 마크다운 파일이나 어디든 호스팅할 수 있는 단일 HTML 페이지를 제공하는 하나의 명령을 원할 것입니다.
이 목록이 바로 그 목적을 위한 것입니다. 여기 있는 모든 도구는 작습니다: 단일 바이너리, npx 한 줄 명령, 또는 한 번 설치하면 잊어버리는 패키지. 빠르게 시작하고, 구성이 거의 필요 없거나 전혀 필요 없으며, 완전한 플랫폼을 뒤에 끌고 다니지 않고 문서화 작업을 수행합니다. 일부는 기존 문서 사이트에 넣을 수 있는 마크다운을 생성합니다. 일부는 독립형 HTML 파일을 생성합니다. 모든 도구는 CI와 터미널에서 실행되며, 이것이 핵심입니다.
더 넓은 범위의 문서화 플랫폼을 원한다면, 최고의 REST API 문서화 도구 요약이 GUI 중심의 도구들을 다룹니다. 이 글은 터미널 우선의, 낮은 설치 공간을 가진 도구들을 다룹니다. 문서 생성기가 무엇을 읽는지에 대한 공식 참조 자료로는, 아래의 모든 도구가 파싱하는 진실의 원천인 OpenAPI Specification이 있습니다.
API 문서화를 위한 CLI 도구가 "경량"이라는 것은 무엇을 의미하는가
경량이라는 것은 성능이 부족하다는 의미가 아닙니다. 이는 설치 공간과 마찰에 관한 것입니다. 네 가지 요소가 이를 결정합니다.
설치 크기 및 의존성. 단일 바이너리 또는 하나의 npm 패키지가 프레임워크보다 낫습니다. 문서 페이지를 생성하는 것이 언어 런타임, 번들러, 플러그인 시스템을 설치해야 한다는 의미라면, 출력물이 어떻든 간에 경량이라고 할 수 없습니다.
시작 및 구성. 이들 중 최고는 사양을 읽고 제로 구성으로 출력을 생성합니다. openapi.yaml에 명령을 지정하면 파일이 반환됩니다. 실행 전에 구성 파일이 필요한 것은 여기서 점수를 잃습니다.
단일 목적 출력. 아래의 각 도구는 하나의 작업을 수행합니다: 사양 입력, 문서 출력. 마크다운 또는 HTML, 다른 것은 추가되지 않습니다. 이것이 파이프라인에서 빠르고 예측 가능하게 유지하는 이유입니다.
어디서든 실행. GUI 없음, 공개 도구의 경우 로그인 없음, 유지할 서버 없음. 노트북에서 작동하며 CI 작업에서도 동일하게 작동합니다. 더 넓은 범위의 무료 옵션을 원한다면 무료 API 문서화 도구 목록에 플랫폼들이 있습니다; 이것은 그중 CLI 부분입니다.
이제 도구들을 가장 작은 것부터 소개합니다.
Widdershins
Widdershins는 이 범주에서 가장 작은 도구입니다. OpenAPI 3, Swagger 2, 또는 AsyncAPI 파일을 마크다운으로 변환하는 단일 npm 패키지입니다. 그것이 전부입니다. 사이트를 렌더링하거나 서버를 실행하지 않습니다; .md 파일을 제공하고 제 할 일을 마칩니다.
npm install -g widdershins
widdershins openapi.yaml -o api-docs.md
생성되는 마크다운은 Slate와 호환되며, 나중에 정적 사이트에 넣을 계획이라면 중요합니다. 유용한 플래그: --omitHeader는 YAML 프론트매터를 제거하고, --language_tabs는 어떤 코드 샘플 언어를 표시할지 제어합니다.
최고의 활용: 사양 콘텐츠를 커밋, 비교, 어떤 문서 시스템에도 넣을 수 있는 마크다운으로 변환하는 것입니다. 솔직한 한계: 마크다운만 얻을 수 있습니다. 스타일링, 대화형 "직접 해보기" 패널, 호스팅된 출력은 없습니다. Widdershins는 렌더러가 아닌 변환기이므로, 마크다운을 사이트로 만드는 다른 도구와 함께 사용해야 합니다.
OpenAPI Generator (문서 생성기)
OpenAPI Generator는 클라이언트 SDK로 가장 잘 알려져 있지만, 문서 생성기도 함께 제공하며, 사양만 있을 때 유용합니다. markdown 생성기는 마크다운 폴더를 작성하고, html2 생성기는 자체 포함된 단일 HTML 페이지를 작성합니다. 직접 Java를 설치하지 않고도 npm 래퍼를 통해 사용할 수 있습니다.
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/
npm 래퍼는 내부적으로 JDK 기반 jar 파일을 다운로드하므로, 첫 실행 시 Widdershins보다 무겁습니다. 그 후에는 한 번의 명령으로 생성됩니다.
최고의 활용: SDK 생성에 이미 사용하고 있을 수 있는 도구를 재사용하여 문서도 생성하고, 마크다운과 독립형 HTML 중에서 선택할 수 있습니다. 솔직한 한계: 출력은 평범하고 템플릿 기반이며, 첫 호출 시 jar 파일을 가져오므로 진정한 단일 바이너리가 아닙니다. 문서만 필요하고 다른 것은 필요 없다면, 더 가벼운 옵션들이 존재합니다.
Redocly CLI (build-docs)
단일 명령으로 보기 좋고 독립형인 HTML 페이지를 원한다면, Redocly CLI가 가장 빠른 방법입니다. build-docs 명령은 Redoc 기반으로 사양을 하나의 자체 포함된 HTML 파일로 묶습니다. 서버도, 별도의 호스팅 빌드도 없습니다; 열거나 이메일로 보내거나 어떤 정적 호스트에도 놓을 수 있는 파일을 얻습니다.
npx @redocly/cli build-docs openapi.yaml
기본적으로 redoc-static.html을 작성합니다. --output으로 이름을 변경하세요:
npx @redocly/cli build-docs openapi.yaml --output api.html
npx를 통해 실행되므로, 전역으로 설치하지 않아도 시도해 볼 수 있습니다. 최고의 활용: 깔끔한 기본 테마와 관리할 호스팅 스토리가 없는, 하나의 명령으로 세련된 단일 페이지 참조 문서를 생성하는 것입니다. 솔직한 한계: 출력은 하나의 HTML 파일이므로, 여러 페이지로 구성된 문서 포털이 아닌 참조 페이지이며, 더 풍부한 테마와 미리보기는 Redocly의 유료 등급에 있습니다. 유사한 렌더러와 비교한다면, Redocly 대안 및 Scalar 대안 비교가 장단점을 설명합니다.
Slate
Slate는 여기서 좀 특이한 도구입니다: 사양을 문서로 변환하는 도구가 아니라, 수기로 작성된 API 문서를 위한 정적 사이트 생성기입니다. 마크다운을 작성하면 Slate는 고전적인 세 열 문서 레이아웃(탐색, 콘텐츠, 코드 샘플이 나란히)을 자체 포함된 정적 사이트로 구축합니다. Middleman을 기반으로 하므로 Ruby가 필요합니다.
# after cloning the slate repo and installing dependencies
bundle exec middleman build
이것은 완전한 정적 사이트를 build/ 폴더에 작성하며, 어디든 호스팅할 수 있습니다. 이것이 Widdershins가 빛을 발하는 지점입니다: 사양에서 마크다운을 생성한 다음 Slate가 렌더링하도록 하면, Slate의 레이아웃으로 사양 기반 콘텐츠를 얻을 수 있습니다.
최고의 활용: 구조와 문체에 대한 편집 제어를 원하는, 수작업으로 선별된 서술형 API 문서. 솔직한 한계: Ruby 툴체인이 필요하고 자체적으로 OpenAPI를 읽지 않기 때문에 이 목록에서 가장 무거운 옵션입니다; 마크다운을 입력해야 합니다. 문서가 사양에서 직접 생성되고 수작업으로 거의 편집되지 않는다면, 변환기만 사용하는 것이 더 가볍습니다.
Apidog CLI (내보내기 + 문서)
위의 오픈 도구들은 각각 변환, 렌더링, 호스팅 중 하나의 역할을 합니다. API가 단일 YAML 파일이 아닌 프로젝트 내에 이미 존재한다면, 이들을 연결하는 것이 번거로울 수 있습니다. 이러한 경우 apidog-cli 바이너리가 적합합니다. 이것은 Apidog의 명령줄 동반 도구이며, 한 번의 내보내기로 빌드 파이프라인 없이 프로젝트를 마크다운 또는 HTML로 변환합니다.
npm에서 설치하고 토큰으로 인증하세요:
npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
그런 다음 하나의 명령으로 프로젝트 문서를 마크다운 또는 HTML로 내보냅니다:
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format html --output ./api-docs.html
CLI는 또한 문서 리소스를 직접 관리합니다. apidog doc은 프로젝트의 마크다운 문서를 처리하고, apidog docs-site는 게시된 문서 사이트를 관리하므로, 스크립트나 CI 작업에서 문서를 나열, 생성 및 업데이트할 수 있습니다:
apidog doc list --project <projectId>
apidog docs-site list --project <projectId>
출력은 구조화된 JSON이므로, 다른 단계로 파이프하거나 에이전트에 쉽게 전달할 수 있습니다. 모든 명령에 대한 자세한 내용은 Apidog CLI 전체 가이드에서 인증, 프로젝트 및 각 명령 그룹을 설명합니다.
여기 솔직한 관점이 있습니다. Apidog는 오픈 소스가 아니며, 단일 목적의 바이너리도 아닙니다; 프리미엄 플랫폼이며, CLI는 호스팅된 프로젝트와 통신합니다. 또한 OpenAPI를 린트하거나 스타일 가이드를 강제하지 않습니다; Redocly와 Spectral이 그 역할을 합니다. CLI가 제공하는 것은 관리되는 API 프로젝트에서 공유 가능한 마크다운 또는 HTML로 가는 통합된 경로이며, 변환기, 렌더러, 호스트를 수동으로 연결하는 대신입니다. 마크다운 내보내기 경로를 특별히 원한다면, 마크다운 내보내기 기능을 갖춘 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 |
요약하자면: 순수한 사양이 있고 커밋할 마크다운을 원한다면 Widdershins를 사용하세요. 공유 가능한 하나의 HTML 페이지를 원한다면 redocly build-docs가 가장 빠릅니다. 문서를 수작업으로 작성하고 적절한 레이아웃을 원한다면 Slate입니다. 그리고 API가 이미 프로젝트 내에 존재하고 하나의 CLI에서 내보내기 및 문서 관리를 원한다면 Apidog입니다. 전반적인 무료 옵션 개요를 원한다면 무료 API 문서화 도구 요약이 이를 정리해 줍니다.
마무리
경량 문서화 도구는 한 가지 규칙으로 요약됩니다: 필요한 출력을 생성하는 가장 작은 것을 선택하세요. Widdershins와 redocly build-docs는 대부분의 사양-문서 변환 사례를 단일 명령으로 처리합니다. OpenAPI Generator는 이미 SDK를 생성하고 있다면 가치가 있습니다. Slate는 문서를 수기로 작성할 때만 더 무거운 설치 공간을 감수할 가치가 있습니다. 그리고 API가 단일 파일이 아닌 실제 프로젝트에 존재한다면, apidog-cli 내보내기는 파이프라인 없이 마크다운 또는 HTML을 제공합니다.
마지막 경우가 당신이라면, Apidog를 다운로드하여 프로젝트에 대해 apidog export를 시도해 보세요; CI 작업에 깔끔하게 통합되어 API가 변경될 때마다 문서가 다시 빌드됩니다.