DEV Community

Cover image for CLI에서 API 문서화하는 방법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

CLI에서 API 문서화하는 방법

API 문서는 사양을 수정한 뒤 참조 문서를 다시 생성하지 않는 순간부터 구식이 됩니다. 이를 막으려면 문서 생성을 수동 작업이 아니라 빌드 단계로 다뤄야 합니다. 단일 명령으로 문서를 생성할 수 있다면, 그 명령을 CI에 연결해 모든 병합 또는 푸시에서 실행할 수 있습니다.

지금 Apidog 사용해 보기

터미널 기반 워크플로우에는 추가 장점도 있습니다.

  • 명령을 스크립트로 관리할 수 있습니다.
  • 생성 결과의 변경 사항을 Git diff로 검토할 수 있습니다.
  • AI 에이전트나 CI 러너가 브라우저 없이 실행할 수 있습니다.
  • GUI 클릭이나 “내보내기 버튼을 눌렀나요?” 같은 수동 확인이 필요 없습니다.

이 글에서는 다음 두 경로를 다룹니다.

  1. OpenAPI 파일을 단일 명령으로 독립형 HTML 또는 Markdown 문서로 변환하는 방법
  2. Apidog CLI를 사용해 라이브 프로젝트에서 문서를 직접 내보내는 방법

관련 도구를 비교하려면 최고의 REST API 문서화 도구 및 무료 API 문서화 도구도 참고할 수 있습니다.

시작하려면 OpenAPI 3.x 파일 하나가 필요합니다. 대부분의 명령은 openapi.yaml과 openapi.json을 모두 입력으로 받을 수 있습니다.

Redocly CLI로 독립형 HTML 참조 만들기

Redocly CLI는 OpenAPI 사양을 독립형 HTML API 참조 문서로 만드는 빠른 방법입니다. 스타일, 스크립트, 콘텐츠가 하나의 HTML 파일에 포함되므로 정적 호스팅에 배포하거나 파일 자체를 공유할 수 있습니다.

1. CLI 설치

전역 설치:

npm install @redocly/cli -g
Enter fullscreen mode Exit fullscreen mode

전역 설치가 부담스럽다면 npx로 실행하는 방식도 사용할 수 있습니다.

2. OpenAPI 사양 빌드 

redocly build-docs openapi.yaml
Enter fullscreen mode Exit fullscreen mode

기본 출력 파일은 현재 디렉터리의 redoc-static.html입니다.

출력 경로를 명시하려면 --output을 사용합니다.

redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

3. 생성 결과 확인 

open docs/index.html
Enter fullscreen mode Exit fullscreen mode

Linux 환경에서는 다음처럼 열 수 있습니다.

xdg-open docs/index.html
Enter fullscreen mode Exit fullscreen mode

이 방식은 다음 조건에 적합합니다.

  • 단일 HTML API 참조가 필요할 때
  • 정적 호스팅에 바로 올릴 결과물이 필요할 때
  • OpenAPI 3.0/3.1 또는 Swagger 2.0 사양을 빠르게 렌더링할 때

다만 build-docs는 API 참조 페이지 생성에 초점이 맞춰져 있습니다. 시작 가이드, 튜토리얼, 마이그레이션 문서처럼 긴 형식의 콘텐츠는 별도로 관리해야 합니다.

Widdershins로 Markdown 생성하기

문서 사이트, 정적 사이트 생성기 또는 저장소의 docs/ 디렉터리에 넣을 파일이 필요하다면 HTML보다 Markdown이 더 적합할 수 있습니다.

Widdershins는 OpenAPI, Swagger, AsyncAPI 정의를 Slate 호환 Markdown으로 변환합니다.

1. 설치 

npm install -g widdershins
Enter fullscreen mode Exit fullscreen mode

2. OpenAPI를 Markdown으로 변환 

widdershins openapi.yaml -o api.md
Enter fullscreen mode Exit fullscreen mode

생성된 api.md를 문서 저장소나 정적 사이트 생성기에 추가하면 됩니다.

3. 코드 샘플 언어 지정

--language_tabs를 사용하면 생성되는 코드 예제 언어를 지정할 수 있습니다.

widdershins openapi.yaml \
  --language_tabs 'shell:cURL' 'python:Python' \
  -o api.md
Enter fullscreen mode Exit fullscreen mode

-o 옵션을 생략하면 결과가 표준 출력으로 전달됩니다. 다른 명령으로 파이프할 때 유용합니다.

widdershins openapi.yaml | tee docs/api.md
Enter fullscreen mode Exit fullscreen mode

Markdown 중심 문서 파이프라인을 운영한다면 Widdershins가 적합합니다. 관련 도구는 Markdown 내보내기를 지원하는 API 문서 생성기 가이드에서도 확인할 수 있습니다.

Redocly와 Widdershins에는 공통적인 주의점이 있습니다. 두 도구 모두 로컬의 정적 파일을 입력으로 읽습니다. 디스크의 openapi.yaml이 실제 API 설계 프로젝트와 동기화되지 않았다면, 생성된 문서도 오래된 상태가 됩니다.

Apidog CLI로 라이브 프로젝트에서 문서화하기

Apidog는 오픈 소스는 아니지만, 무료 등급과 apidog-cli를 제공합니다. 엔드포인트, 스키마, 작성형 문서를 하나의 프로젝트에서 관리하고 CLI로 해당 프로젝트의 현재 상태를 내보내는 방식입니다.

즉, 로컬 파일을 따로 동기화하지 않고 팀이 편집하는 프로젝트를 문서 생성의 소스로 사용할 수 있습니다.

1. CLI 설치 

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

처음 설치한다면 Apidog CLI 설치 가이드에서 Node.js 버전과 PATH 설정을 확인할 수 있습니다.

2. 액세스 토큰으로 로그인 

apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

토큰은 실행 머신에 저장되므로 이후 명령마다 전달할 필요는 없습니다.

CLI 버전에 따른 정확한 옵션은 항상 --help로 확인합니다.

apidog --help
apidog export --help
Enter fullscreen mode Exit fullscreen mode

프로젝트로 OpenAPI 사양 가져오기

이미 OpenAPI 파일이 있다면 먼저 Apidog 프로젝트로 가져옵니다.

apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

apidog import는 다음 형식을 지원합니다.

  • OpenAPI 3.x
  • Swagger 2.0
  • Postman
  • Apidog 형식

가져온 사양은 이후 내보내기와 문서 관리의 기준이 되는 프로젝트 소스가 됩니다.

사람이 읽을 수 있는 문서 내보내기

apidog export를 사용하면 프로젝트의 현재 상태를 OpenAPI, HTML, Markdown, Postman 형식으로 내보낼 수 있습니다.

먼저 현재 CLI 버전에서 지원하는 정확한 형식과 출력 옵션을 확인합니다.

apidog export --help
Enter fullscreen mode Exit fullscreen mode

Markdown으로 내보내기 

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

생성된 api-docs.md는 프로젝트의 현재 상태를 기준으로 생성된 API 참조 문서입니다.

HTML로 내보내기 

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

OpenAPI 파일로 다시 내보내기

다른 도구나 다운스트림 파이프라인에 전달할 사양이 필요하다면 OpenAPI로도 내보낼 수 있습니다.

apidog export \
  --project <projectId> \
  --format openapi \
  --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

프로젝트에 여러 서비스가 있다면 일부만 내보내야 할 수 있습니다. 이 경우 현재 CLI 버전에서 제공하는 범위 및 ID 관련 옵션을 확인합니다.

apidog export --help
Enter fullscreen mode Exit fullscreen mode

작성형 가이드 문서 관리하기

API 참조 문서만으로는 충분하지 않은 경우가 많습니다. 다음과 같은 문서도 함께 관리해야 합니다.

  • 시작 가이드
  • 인증 절차
  • 마이그레이션 노트
  • 사용 시나리오
  • SDK 설정 가이드

Apidog에서는 이러한 문서를 프로젝트 문서 트리의 Markdown 문서로 관리하며, CLI에서는 doc 명령 그룹을 사용합니다.

apidog doc --help
apidog doc list --project <projectId>
Enter fullscreen mode Exit fullscreen mode

명령이 JSON 페이로드를 요구하는 경우에는 예상 스키마를 먼저 확인하고 로컬에서 검증하는 것이 안전합니다.

apidog cli-schema --help
Enter fullscreen mode Exit fullscreen mode

명령 결과에 포함되는 agentHints.nextSteps도 다음 작업을 판단하는 데 사용할 수 있습니다.

문서 사이트 게시하기

참조 문서와 가이드가 준비되면 CLI로 공개 문서 사이트와 공유 링크를 관리할 수 있습니다.

apidog docs-site --help
apidog shared-doc --help
Enter fullscreen mode Exit fullscreen mode

명령의 역할은 구분해서 사용합니다.

명령 용도
doc 프로젝트 API 트리 안의 Markdown 문서 관리
docs-site 호스팅되는 공개 문서 사이트 관리
shared-doc 공유 가능한 문서 링크 관리

UI에서 수동으로 공개 사이트를 구성하는 대신 스크립트로 관리하려면 docs-site를 사용합니다. 특정 파트너나 팀원에게 전달할 공유 링크만 필요하다면 shared-doc가 적합합니다.

이 흐름을 자동화하면 다음 순서가 됩니다.

  1. 사양을 프로젝트로 가져오거나 프로젝트에서 수정합니다.
  2. 문서를 내보냅니다.
  3. 게시 명령을 실행합니다.
  4. 호스팅된 문서에 변경 사항이 반영됩니다.

CI에 연결하기

CLI를 사용하는 핵심 이유는 반복성입니다. 로컬에서 실행되는 명령은 CI에서도 실행할 수 있습니다.

다음은 GitHub Actions에서 Markdown API 문서를 재생성하는 최소 예시입니다.

- name: Regenerate API docs
  run: |
    npm install -g apidog-cli
    apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
    apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md
Enter fullscreen mode Exit fullscreen mode

APIDOG_TOKEN과 APIDOG_PROJECT는 워크플로우 파일에 직접 작성하지 말고 GitHub Actions Secrets로 저장해야 합니다.

Redocly를 사용하는 경우에는 다음처럼 바꿀 수 있습니다.

- name: Build Redocly docs
  run: |
    npm install -g @redocly/cli
    redocly build-docs openapi.yaml --output docs/index.html
Enter fullscreen mode Exit fullscreen mode

Widdershins를 사용한다면 다음과 같습니다.

- name: Generate Markdown API docs
  run: |
    npm install -g widdershins
    widdershins openapi.yaml -o docs/api.md
Enter fullscreen mode Exit fullscreen mode

이제 문서는 누군가 기억해서 실행해야 하는 작업이 아니라, 사양 변경 시 자동으로 재생성되는 빌드 아티팩트가 됩니다. 전체 명령은 Apidog CLI 전체 가이드에서 확인할 수 있습니다.

일반적인 문제점

잘못되었거나 누락된 프로젝트 ID

Apidog의 export, doc, docs-site 명령은 모두 --project <projectId>가 필요합니다.

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

여기서 필요한 값은 사람이 읽는 프로젝트 이름이 아니라 프로젝트 설정에서 확인할 수 있는 프로젝트 ID입니다. 프로젝트 관련 오류가 발생하면 가장 먼저 ID를 확인하세요.

CI에 토큰이 설정되지 않음

apidog login은 실행 중인 머신에 토큰을 저장합니다. CI 러너는 매 실행마다 새 환경일 수 있으므로, 내보내기 전 같은 작업 안에서 로그인해야 합니다.

apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

토큰은 반드시 CI 비밀값으로 관리하세요.

오래된 OpenAPI 파일 사용

Redocly와 Widdershins는 전달받은 파일을 그대로 읽습니다.

redocly build-docs openapi.yaml
widdershins openapi.yaml -o api.md
Enter fullscreen mode Exit fullscreen mode

따라서 openapi.yaml이 오래되었다면 생성된 문서도 오래된 상태입니다. Apidog CLI 방식은 디스크의 복사본 대신 라이브 프로젝트에서 내보내므로 이 불일치를 줄일 수 있습니다.

--help 없이 플래그를 추측함

export, doc, docs-site, shared-doc의 세부 플래그는 CLI 버전에 따라 달라질 수 있습니다. 반쯤 기억한 옵션을 사용하기보다 실행 전에 도움말을 확인하세요.

apidog export --help
apidog doc --help
apidog docs-site --help
apidog shared-doc --help
Enter fullscreen mode Exit fullscreen mode

몇 초만 투자하면 CI 실패와 잘못된 내보내기를 줄일 수 있습니다.

마무리

터미널에서 API 문서를 생성할 때는 필요한 출력 형식과 문서 소스를 먼저 선택하면 됩니다.

  • 독립형 HTML API 참조가 필요하면 Redocly CLI를 사용합니다.
  • 문서 사이트용 Markdown이 필요하면 Widdershins를 사용합니다.
  • API 참조, 작성형 가이드, 게시 사이트를 하나의 라이브 프로젝트에서 관리하려면 Apidog CLI를 사용합니다.

중요한 점은 어떤 도구를 선택하든 생성 명령을 CI에 연결하는 것입니다. 한 번 설정하면 사양이 바뀔 때마다 문서도 자동으로 다시 생성됩니다.

CLI를 설치하고 프로젝트 내보내기 흐름을 테스트하려면 Apidog 다운로드를 확인하거나, Apidog가 API 우선 워크플로우에 어떻게 적용되는지 살펴보세요.

Top comments (0)