API 문서는 누군가 사양을 편집하고 참조를 다시 생성하는 것을 잊는 순간 구식이 됩니다. 해결책은 문서를 수동 단계로 취급하는 것을 중단하는 것입니다. 단일 명령으로 문서를 생성할 수 있다면, 그 명령을 CI에 연결하여 모든 병합 시 실행되도록 할 수 있습니다.
터미널에서 작업을 수행하는 것은 다른 장점도 있습니다. 명령은 스크립트화할 수 있고, 검토할 수 있는 차이점을 남기며, AI 에이전트나 CI 러너가 브라우저를 열 필요 없이 명령을 트리거할 수 있습니다. GUI 클릭도, "내보내기 버튼 누르는 것을 잊었나요?"와 같은 질문도 필요 없습니다.
이 가이드는 먼저 일반적인 공개 경로를 다룹니다: OpenAPI 파일을 단일 명령으로 독립형 HTML 참조 또는 Markdown 파일로 변환하는 것입니다. 그런 다음 Apidog CLI 경로를 자세히 설명합니다. 이는 라이브 프로젝트에서 바로 문서를 가져와서 원본 소스와 출력이 동기화되도록 합니다. 이 분야에 대한 더 많은 배경 지식을 원하시면, 최고의 REST API 문서화 도구와 알아둘 가치가 있는 무료 API 문서화 도구에 대한 저희의 요약 정보를 참조하십시오.
따라하려면 한 가지가 필요합니다: OpenAPI 3.x 파일입니다. 이러한 명령 대부분은 openapi.yaml 또는 openapi.json을 상호 교환적으로 허용합니다.
Redocly CLI로 HTML 참조 빌드하기
Redocly CLI는 OpenAPI 설명을 세련되고 독립적인 HTML 페이지로 바꾸는 가장 빠른 방법입니다. Redoc으로 사양을 렌더링하고 모든 것(스타일, 스크립트, 콘텐츠)을 하나의 파일에 작성하여 어디든 호스팅하거나 팀원에게 이메일로 보낼 수 있습니다.
전역으로 설치하거나, 설치를 건너뛰고 npx로 실행하십시오:
npm install @redocly/cli -g
그런 다음 사양을 가리키십시오:
redocly build-docs openapi.yaml
기본적으로 이 명령은 현재 디렉토리에 redoc-static.html을 작성합니다. 해당 파일을 브라우저에서 열면 전체 3패널 API 참조를 볼 수 있습니다. 파일 이름이나 경로를 제어하려면 --output을 사용하십시오:
redocly build-docs openapi.yaml --output docs/index.html
이것이 전체 워크플로우입니다. 하나의 입력 파일, 하나의 명령, 하나의 HTML 아티팩트. Swagger 2.0 및 OpenAPI 3.0/3.1 설명과 호환되므로 대부분의 기존 사양은 변경 없이 렌더링됩니다. 단점은 범위입니다: build-docs는 참조 페이지 외에는 아무것도 제공하지 않습니다. 긴 형식의 가이드, 튜토리얼, 시작 페이지는 이 범위 밖에 있습니다.
Widdershins로 마크다운 생성하기
때로는 HTML이 필요하지 않을 때가 있습니다. 문서 사이트, 정적 사이트 생성기 또는 저장소의 docs/ 폴더에 넣을 수 있는 마크다운이 필요할 때가 있습니다. Widdershins는 OpenAPI, Swagger 또는 AsyncAPI 정의를 Slate 호환 마크다운으로 변환합니다.
npm에서 설치하십시오:
npm install -g widdershins
그런 다음 사양을 변환하고, 출력을 -o 옵션을 사용하여 파일로 보내십시오:
widdershins openapi.yaml -o api.md
-o를 생략하면 Widdershins는 표준 출력으로 인쇄하며, 이는 다른 곳으로 파이프하고 싶을 때 유용합니다. 코드 샘플에 대한 언어 탭을 전환할 수도 있습니다:
widdershins openapi.yaml --language_tabs 'shell:cURL' 'python:Python' -o api.md
문서 파이프라인이 마크다운 우선일 때 Widdershins는 적합합니다. 더 넓은 마크다운 내보내기 흐름을 구축하고 있다면, 마크다운 내보내기를 지원하는 API 문서 생성기 사용에 대한 저희 가이드가 관련 도구를 다룹니다. Redocly와 Widdershins의 공통적인 문제점은 정적 파일을 읽는다는 것입니다. API 정의가 디자인 도구에 있고 디스크의 파일과 달라지면, 어제의 사양을 문서화하는 셈입니다.
Apidog CLI로 라이브 프로젝트에서 문서화하기
여기서 통합 경로의 이점이 나타납니다. Apidog는 오픈 소스가 아니지만, 무료 등급과 apidog-cli는 여러 도구를 함께 엮는 대신 대안을 제공합니다: 엔드포인트, 스키마, 작성된 문서가 모두 하나의 프로젝트에 존재하며, CLI는 필요에 따라 해당 프로젝트에서 내보내기합니다. 내보내기는 팀이 편집하는 동일한 소스를 읽기 때문에 아무것도 어긋나지 않습니다.
npm에서 CLI를 설치하십시오:
npm install -g apidog-cli
처음 설정하는 경우, 저희의 Apidog CLI 설치 가이드가 Node 버전 및 PATH 설정을 다룹니다. 그런 다음 개인 액세스 토큰으로 한 번 인증하십시오:
apidog login --with-token <TOKEN>
토큰은 저장되므로 모든 호출에서 전달할 필요가 없습니다. 이제부터 모든 것은 프로젝트 ID를 기준으로 실행됩니다. 명령을 실행하기 전에 정확한 플래그를 보려면 어떤 명령이든 --help를 추가하십시오.
프로젝트로 사양 가져오기
API가 이미 OpenAPI 파일에 있다면, CLI가 내보낼 수 있도록 프로젝트로 가져오십시오:
apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
apidog import는 OpenAPI 3.x, Swagger 2.0, Postman 및 Apidog 형식을 허용하므로 Postman 컬렉션 또는 기존 Apidog 내보내기를 동일한 방식으로 가져올 수 있습니다. 사양이 가져오기되면, 다른 모든 것이 읽어들이는 라이브 소스가 됩니다.
사람이 읽을 수 있는 문서 내보내기
이것이 핵심 명령입니다. apidog export는 OpenAPI, HTML, Markdown 또는 Postman을 작성하므로, 먼저 --help를 실행하여 현재 버전에 있는 정확한 형식 및 출력 플래그를 확인한 다음, 프로젝트 문서를 Markdown으로 내보내십시오:
apidog export --help
apidog export --project <projectId> --format markdown --output ./api-docs.md
api-docs.md를 열면 프로젝트의 현재 상태에서 생성된 전체 참조를 볼 수 있습니다. HTML을 원하십니까? 플래그 하나만 변경하십시오:
apidog export --project <projectId> --format html --output ./api-docs.html
다운스트림에 전달할 휴대용 사양이 필요할 때는 OpenAPI로 다시 내보낼 수도 있습니다:
apidog export --project <projectId> --format openapi --output ./openapi.json
프로젝트에 여러 서비스가 있고 그 중 일부만 문서화하고 싶다면, 내보내기는 범위를 좁히는 것을 지원합니다. 단일 프로젝트가 서비스당 하나의 문서 파일을 그렇게 배포할 수 있으므로, 현재 버전의 범위 및 ID 플래그에 대해서는 apidog export --help를 확인하십시오.
참조뿐만 아니라 작성된 가이드 관리하기
스키마에서 생성된 참조는 이야기의 절반에 불과합니다. 나머지 절반은 설명입니다: 시작 가이드, 인증 절차, 마이그레이션 노트. Apidog에서는 이들이 프로젝트의 문서 트리에 마크다운 문서로 존재하며, CLI는 doc 명령 그룹으로 이들을 관리합니다.
현재 버전에 포함된 정확한 플래그를 기반으로 작업할 수 있도록 먼저 그룹의 도움말을 읽으십시오:
apidog doc --help
apidog doc list --project <projectId>
거기서부터 흐름은 CLI의 다른 모든 것과 동일합니다: 프로젝트에 대해 명령을 실행하고, JSON 결과를 읽고, 반환되는 agentHints.nextSteps를 따르십시오. 명령이 JSON 페이로드를 원할 때, CLI는 예상하는 스키마를 인쇄하고 아무것도 보내기 전에 파일을 검증할 수 있으므로, 실패한 호출에서가 아니라 자신의 머신에서 누락된 필드를 발견할 수 있습니다. 정확한 유효성 검사 하위 명령에 대해서는 apidog cli-schema --help를 확인하십시오.
문서 사이트 게시하기
참조 및 가이드가 준비되면, 터미널에서도 게시된 문서를 관리할 수 있습니다. 두 가지 명령이 이를 다루며, 먼저 도움말을 읽으면 추측하는 플래그를 절약할 수 있습니다:
apidog docs-site --help
apidog shared-doc --help
사람들을 헷갈리게 하는 한 가지 명명 규칙: doc은 프로젝트 API 트리 내의 마크다운 문서이며, docs-site는 호스팅되는 공개 문서 사이트를 관리하고, shared-doc은 공유 가능한 문서 링크를 관리합니다. UI에서 클릭하여 정의하는 대신 터미널에서 정의된 공개 사이트를 원할 때 docs-site를 사용하고, 파트너에게 전달할 링크만 필요할 때 shared-doc를 사용하십시오. 그 결과로 게시가 스크립트화된 단계가 됩니다: 사양이 변경되면 프로젝트를 다시 가져오거나 편집한 다음 게시 명령을 다시 실행하면, 호스팅된 문서가 업데이트를 반영합니다.
CI에 연결하기
CLI에서 이 모든 것을 실행하는 이유는 반복성 때문입니다. 명령이 로컬에서 작동하면, 파이프라인에서도 작동합니다. 모든 푸시에서 마크다운 참조를 재생성하고 커밋하는 최소한의 GitHub Actions 단계는 다음과 같습니다:
- 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
redocly build-docs 또는 widdershins로 바꾸어도 형태는 동일합니다. 문서는 누군가 기억해서 해야 하는 귀찮은 일이 아니라, 스스로 재생성되는 빌드 아티팩트가 됩니다. 전체 명령 참조는 Apidog CLI 전체 가이드를 참조하십시오.
일반적인 문제점
잘못되었거나 누락된 프로젝트 ID. 모든 Apidog export, doc, docs-site 호출에는 --project <projectId>가 필요합니다. ID는 프로젝트 설정에 있으며, 사람이 읽을 수 있는 프로젝트 이름이 아닙니다. 명령이 프로젝트에 대해 오류를 발생시키면, 거의 항상 이것이 원인입니다.
CI에 토큰이 설정되지 않음. apidog login은 실행하는 머신에 토큰을 저장합니다. 새 CI 러너에는 저장된 토큰이 없으므로, 내보내기 전에 동일한 작업에서 login --with-token을 실행해야 합니다. 토큰은 워크플로우 파일이 아닌 비밀(secret)로 저장하십시오.
오래된 파일 내보내기. Redocly와 Widdershins는 전달하는 모든 파일을 읽습니다. openapi.yaml이 오래되었다면, 문서도 오래된 것입니다. 이것이 Apidog 경로가 디스크의 파일 대신 라이브 프로젝트에서 내보내기하여 피하는 정확한 불일치입니다.
--help를 읽지 않고 플래그를 추측하는 것. export, doc, docs-site, shared-doc에 대한 정확한 플래그는 CLI 버전에 따라 다를 수 있습니다. apidog <command> --help를 실행하고 반쯤 기억하는 플래그 대신 인쇄되는 내용을 기반으로 작업하십시오. 이는 2초가 걸리지만 실패한 빌드를 막아줍니다.
마무리
터미널에서 API를 문서화하는 것은 올바른 출력을 선택하는 것으로 귀결됩니다. 독립형 HTML 참조를 원할 때는 Redocly CLI를, 문서 사이트용 마크다운을 원할 때는 Widdershins를, 그리고 참조와 작성된 가이드 및 게시된 사이트 모두를 하나의 라이브 소스에서 내보내고 싶을 때는 Apidog CLI를 사용하십시오. 마지막 옵션은 내보내기된 내용과 팀이 편집하는 것이 동일한 프로젝트이기 때문에 문서의 신뢰성을 유지하는 방법입니다.
여기에 있는 모든 명령은 스크립트화할 수 있으며, 이는 모든 명령이 CI에 속한다는 것을 의미합니다. 한 번 설정하면 변경될 때마다 문서가 자동으로 재생성됩니다. CLI를 얻고 자신의 프로젝트에 대해 내보내기 흐름을 시도하려면 Apidog 다운로드를 방문하거나, Apidog가 API 우선 워크플로우에 어떻게 적합한지에 대해 자세히 읽어보십시오.