DEV Community

Cover image for AI 에이전트가 Apidog CLI로 API 문서를 생성하는 방법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

AI 에이전트가 Apidog CLI로 API 문서를 생성하는 방법

API 문서는 모두가 중요하다고 동의하지만, 아무도 맡고 싶어 하지 않는 작업입니다. 새 엔드포인트가 출시된 뒤 참조 문서는 일주일 늦게 업데이트되고, 시작하기 가이드는 두 스프린트 전에 바뀐 인증 흐름을 설명하기 쉽습니다. 이 작업은 중요하지만 반복적이고 미루기 쉽습니다.

지금 Apidog 사용해 보기

이 조합(중요함, 반복적임, 미루기 쉬움)은 AI 에이전트가 잘 처리하는 영역입니다. 에이전트가 터미널 명령을 실행할 수 있다면 일반 언어 요청만으로 엔드포인트를 만들고, 관련 가이드를 작성하고, 문서 사이트를 게시할 수 있습니다. Apidog CLI는 이를 위한 스크립트 가능한 명령을 제공하며, 모든 호출은 에이전트가 읽고 다음 작업을 결정할 수 있는 구조화된 JSON 출력을 반환합니다.

GUI나 MCP 서버가 아닌 CLI를 사용하는 이유

에이전트가 API 문서를 다루는 방식은 크게 세 가지입니다. 각 방식은 해결하는 문제가 다릅니다.

접근 방식 방향 누가 주도하는가 검토 가능한 차이점?
GUI 브라우저에서 사람이 편집 클릭하는 사람 아니요
MCP 서버 사양을 읽고 코드 작성 편집기 내 에이전트 코드 리포에는 있음, 문서에는 없음
CLI 문서 자체를 작성 터미널 내 에이전트 예, 모든 명령이 기록됨

MCP 서버는 에이전트가 API 정의를 읽고 그에 맞는 클라이언트 코드를 만들 때 유용합니다. Cursor에서 MCP로 문서 흐름 구성하기가 대표적인 사례입니다.

하지만 여기서 목표는 반대입니다. 에이전트가 문서를 생성해야 합니다. 즉, 엔드포인트를 만들고, Markdown 가이드를 작성하고, 문서 사이트를 게시해야 합니다.

CLI가 적합한 이유는 다음과 같습니다.

  1. 결정론적 실행: 같은 명령은 같은 결과를 만듭니다.
  2. 자동화 가능: 에이전트 작업 루프와 CI에 그대로 연결할 수 있습니다.
  3. 구조화된 응답: 모든 호출이 JSON을 반환하며, agentHints.nextSteps에서 다음 작업 후보를 제공합니다.

에이전트가 다음 단계를 추측하게 하지 말고, CLI 응답의 agentHints.nextSteps를 읽도록 지시하세요.

에이전트 환경 설정하기

먼저 CLI를 설치하고 인증합니다. Node 버전과 PATH 설정은 설치 가이드를, 토큰 관리와 CI 보안은 인증 가이드를 참고하세요.

npm install -g apidog-cli
apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

Apidog CLI 설치 및 인증 화면

Apidog 앱에서 사용자 아바타 → 계정 설정 → API 접근 토큰으로 이동해 토큰을 가져옵니다. 로그인 후 토큰은 로컬에 저장되므로, 에이전트가 모든 호출에 토큰을 직접 전달할 필요는 없습니다.

Apidog API 접근 토큰 화면

모든 쓰기 작업은 프로젝트 ID를 기준으로 실행됩니다. 프로젝트 설정의 기본 설정에서 확인하거나 다음 명령으로 찾을 수 있습니다.

apidog project list
Enter fullscreen mode Exit fullscreen mode

셸 명령을 실행할 수 있는 코딩 에이전트라면 사용할 수 있습니다. 예를 들어 Claude Code, Cursor, Codex가 해당합니다.

에이전트에서 Apidog CLI를 실행하는 예시

Apidog CLI 작업 흐름 예시

에이전트가 따라야 할 쓰기 규칙

리소스를 생성하거나 업데이트하는 명령은 JSON 파일을 입력으로 사용합니다. 이 JSON을 에이전트가 추측해서 만들면 실패하기 쉽습니다. 모델이 임의로 만든 필드명, 누락된 필수 필드, 잘못된 중첩 구조가 대표적인 원인입니다.

모든 쓰기 작업에서 다음 네 단계를 고정하세요.

# 1. 대상 명령의 입력 스키마를 조회합니다.
apidog cli-schema get doc-create

# 2. 조회한 스키마를 기준으로 JSON 파일을 작성합니다.

# 3. 로컬에서 JSON을 검증합니다.
apidog cli-schema validate doc-create --file ./doc.json

# 4. 검증이 통과한 경우에만 생성 명령을 실행합니다.
apidog doc create --project <projectId> --file ./doc.json
Enter fullscreen mode Exit fullscreen mode

에이전트의 시스템 프롬프트, CLAUDE.md, .cursorrules 등에 다음 규칙을 추가할 수 있습니다.

Apidog CLI 규칙:
- JSON 페이로드를 직접 추측해 작성하지 마십시오. 먼저 `apidog cli-schema get <명령>`을 실행하고, 반환된 스키마를 기반으로 파일을 만드십시오.
- 모든 create 또는 update 전에 `apidog cli-schema validate <명령> --file <파일>`로 검증하십시오.
- 모든 쓰기 명령에 `--project <projectId>`를 전달하십시오.
- 다음 명령을 선택할 때 각 JSON 응답의 `agentHints.nextSteps` 필드를 읽으십시오.
- 쓰기 작업이 권한 때문에 차단되면 작업을 중단하고 사람에게 문의하십시오. 우회 방법을 찾지 마십시오.
Enter fullscreen mode Exit fullscreen mode

핵심은 다음 순서입니다.

스키마 조회 → JSON 작성 → 로컬 검증 → 생성 또는 업데이트

이 순서를 강제하면 “에이전트가 필드를 임의로 만들었다”는 문제를 “검증기가 로컬에서 차단했다”는 문제로 바꿀 수 있습니다.

1단계: 엔드포인트와 스키마에서 참조 생성

Apidog의 API 참조는 프로젝트에 등록된 엔드포인트와 데이터 스키마에서 생성됩니다. 따라서 에이전트는 데이터 모델과 엔드포인트를 먼저 만들어야 합니다.

예를 들어 에이전트에 다음과 같이 요청한다고 가정해 보겠습니다.

“주문 ID와 금액을 받는 POST /refunds 엔드포인트를 추가하고, 성공 및 유효성 검사 오류 응답을 문서화하세요.”

먼저 재사용 가능한 환불 데이터 모델을 만듭니다. schema-create 스키마를 조회합니다.

apidog cli-schema get schema-create
Enter fullscreen mode Exit fullscreen mode

데이터 스키마에는 name과 표준 jsonSchema 객체가 필요합니다. 예를 들어 refund-schema.json은 다음과 같습니다.

{
  "name": "Refund",
  "description": "주문에 대해 발행된 환불",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amount"],
    "properties": {
      "orderId": { "type": "string" },
      "amount": { "type": "number" },
      "reason": { "type": "string" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

검증한 뒤 생성합니다.

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json
Enter fullscreen mode Exit fullscreen mode

생성 결과에서 스키마 ID를 확인한 뒤, 엔드포인트 JSON에서 해당 스키마를 참조합니다. endpoint-create 스키마를 먼저 조회하세요.

apidog cli-schema get endpoint-create
Enter fullscreen mode Exit fullscreen mode

refunds-endpoint.json 예시입니다.

{
  "name": "환불 생성",
  "method": "post",
  "path": "/refunds",
  "status": "developing",
  "requestBody": {
    "type": "application/json",
    "jsonSchema": {
      "$ref": "#/definitions/<refundSchemaId>"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

검증 후 엔드포인트를 생성합니다.

apidog cli-schema validate endpoint-create --file ./refunds-endpoint.json
apidog endpoint create --project <projectId> --file ./refunds-endpoint.json
Enter fullscreen mode Exit fullscreen mode

이제 /refunds의 참조 문서는 팀이 편집하는 동일한 정의에서 렌더링됩니다. 별도의 “문서 내보내기” 단계가 필요한 것이 아닙니다. 엔드포인트가 등록되면 프로젝트의 참조 문서에 바로 반영됩니다.

2단계: 참조 문서뿐 아니라 가이드 작성

스키마 기반 참조 문서는 문서화의 절반입니다. 나머지 절반은 시작하기, 인증, 마이그레이션, 운영 가이드 같은 설명 문서입니다.

Apidog에서는 이러한 문서가 프로젝트 문서 트리에 Markdown 문서로 저장되며, doc 명령 그룹으로 관리됩니다.

doc-create 스키마를 조회합니다.

apidog cli-schema get doc-create
Enter fullscreen mode Exit fullscreen mode

doc-create에는 최소한 name이 필요합니다. content에는 Markdown을 넣고, folderId로 문서 위치를 지정합니다. folderId: 0은 루트 폴더를 의미합니다.

예를 들어 quickstart.json은 다음과 같이 작성할 수 있습니다.

{
  "name": "퀵스타트: 첫 환불",
  "content": "# 퀵스타트\n\n이 가이드는 API 키 발급부터 첫 환불 요청까지 5분 안에 안내합니다...",
  "folderId": 0
}
Enter fullscreen mode Exit fullscreen mode

문서 트리를 확인하고, JSON을 검증한 뒤 생성합니다.

apidog doc list --project <projectId>
apidog cli-schema validate doc-create --file ./quickstart.json
apidog doc create --project <projectId> --file ./quickstart.json
Enter fullscreen mode Exit fullscreen mode

이제 에이전트에게 다음처럼 작업을 요청할 수 있습니다.

“새 개발자가 API 키 발급부터 첫 환불까지 완료할 수 있는 퀵스타트를 작성해.”

에이전트는 Markdown 초안을 만들고, 스키마에 맞는 JSON으로 감싸고, 검증한 후 문서를 생성합니다. 브라우저에서 복사·붙여넣기 할 필요가 없습니다.

3단계: 문서 사이트 게시

참조와 가이드가 준비되면 에이전트는 터미널에서 문서 사이트까지 게시할 수 있습니다. 다음 명령 그룹의 역할을 구분해야 합니다.

  • doc: 프로젝트 API 트리 내부의 Markdown 문서
  • docs-site: 호스팅되는 공개 문서 사이트
  • shared-doc: 전체 사이트가 아닌 공유 링크

공개 문서 사이트를 만들려면 다음 흐름을 사용합니다.

apidog docs-site list --project <projectId>
apidog cli-schema get docs-site-create
apidog cli-schema validate docs-site-create --file ./docs-site.json
apidog docs-site create --project <projectId> --file ./docs-site.json
Enter fullscreen mode Exit fullscreen mode

터미널에서 정의한 공개 문서 사이트가 필요하면 docs-site를 사용하세요. 특정 파트너나 사용자에게 보낼 링크만 필요하면 shared-doc를 사용합니다.

이 작업도 명령이므로, 모든 문서 변경 뒤에 에이전트가 실행하는 스크립트 단계로 포함할 수 있습니다. 명령이 반환되는 시점에 호스팅된 사이트에 업데이트가 반영됩니다.

4단계: 휴대용 복사본 내보내기

문서를 다른 곳에서 호스팅하거나 정적 사이트 생성기에 전달해야 할 수도 있습니다. 이때 export 명령으로 HTML, Markdown, OpenAPI 파일을 생성할 수 있습니다.

apidog export --project <projectId> --format html --output ./api-docs.html
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

프로젝트에 여러 서비스가 있고 일부만 내보내려면 도움말에서 범위 제한 옵션을 확인하세요.

apidog export --help
Enter fullscreen mode Exit fullscreen mode

--scope, --api-ids, --folder-ids 플래그를 사용하면 서비스별 문서 파일을 배포할 수 있습니다.

전체 작업 예시

다음 요청을 생각해 보겠습니다.

당신: “POST /refunds와 GET /refunds/{id}가 포함된 결제 서비스를 새로 추가했습니다. 두 API를 모두 문서화하고, 멱등 키에 대한 짧은 가이드를 작성한 다음 문서 사이트에 게시하세요.”

에이전트는 스키마 조회와 검증 규칙을 적용해 다음 작업을 수행합니다.

# 공유 데이터 모델 생성
apidog cli-schema get schema-create
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json

# 두 엔드포인트 생성
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./post-refunds.json
apidog endpoint create --project $PID --file ./post-refunds.json

apidog cli-schema validate endpoint-create --file ./get-refund.json
apidog endpoint create --project $PID --file ./get-refund.json

# 멱등성 가이드 작성
apidog cli-schema get doc-create
apidog cli-schema validate doc-create --file ./idempotency-guide.json
apidog doc create --project $PID --file ./idempotency-guide.json

# 문서 사이트 게시
apidog cli-schema get docs-site-create
apidog cli-schema validate docs-site-create --file ./docs-site.json
apidog docs-site create --project $PID --file ./docs-site.json
Enter fullscreen mode Exit fullscreen mode

검토 대상은 에이전트의 자연어 설명이 아니라 생성된 스키마, 엔드포인트, Markdown 문서, 게시 설정의 변경 사항입니다.

에이전트 루프 또는 CI에 연결하기

모든 단계가 명령이므로 에이전트 작업 루프나 CI 파이프라인에 연결할 수 있습니다. 예를 들어 푸시마다 Markdown 참조를 다시 생성하려면 다음 단계를 사용할 수 있습니다.

- name: API 문서 재생성
  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

CLI로 에이전트 작업을 처음부터 끝까지 구성하는 방법은 PRD에서 테스트 루프까지와 완벽한 API를 구축하기 위해 5개의 AI 에이전트를 설정하는 방법을 참고하세요.

패턴은 동일합니다.

  1. 의도를 설명합니다.
  2. 에이전트가 검증된 CLI 호출로 변환하게 합니다.
  3. 결과와 변경 사항을 검토합니다.

권한 참고 사항

에이전트의 프로젝트 쓰기 작업은 권한으로 제한될 수 있습니다. create 명령이 차단된다면 해당 브랜치에서 외부 AI 편집 권한이 꺼져 있을 수 있습니다.

선택지는 두 가지입니다.

  1. 프로젝트 설정 → 기능 설정 → AI 기능 설정에서 직접 편집 권한을 활성화합니다. 이 설정은 Apidog 클라이언트 2.8.32 이상에서 사용할 수 있습니다.
  2. 에이전트가 격리된 AI 브랜치에서 작업하고 병합 요청을 열도록 합니다.

API 사양 업데이트 동반 가이드는 AI 브랜치 흐름을 자세히 설명합니다. 보호된 브랜치에서 문서를 생성할 때도 같은 방식이 적용됩니다.

일반적인 문제

에이전트가 JSON을 직접 만들었습니다

가장 흔한 실패 원인입니다. 에이전트 지침에 아래 순서를 강제하세요.

cli-schema get → cli-schema validate → create
Enter fullscreen mode Exit fullscreen mode

에이전트가 추측한 구조가 아니라 CLI가 제공한 실제 스키마를 사용해야 합니다.

프로젝트 ID가 누락되었습니다

모든 doc, docs-site, export 호출에는 --project가 필요합니다. 사람이 읽는 프로젝트 이름이 아니라 프로젝트 설정에서 확인한 ID를 전달해야 합니다.

doc, docs-site, shared-doc를 혼동했습니다

세 명령은 서로 다른 대상을 다룹니다.

  • doc: 프로젝트 트리 내부의 Markdown 페이지
  • docs-site: 호스팅된 문서 사이트
  • shared-doc: 공유 링크

에이전트가 명령을 실행하기 전에 원하는 결과물이 무엇인지 명확히 지정하세요.

CI에 토큰이 설정되지 않았습니다

apidog login은 토큰을 현재 실행 머신에 저장합니다. 새 CI 러너에는 토큰이 없으므로, 작업 내에서 login --with-token을 먼저 실행해야 합니다. 토큰은 반드시 secret으로 관리하세요.

아무것도 가리키지 않는 $ref가 있습니다

엔드포인트가 #/definitions/{schemaId}로 데이터 모델을 참조한다면, 해당 스키마가 먼저 생성되어 있어야 합니다. 스키마 생성 결과에서 ID를 얻은 후 엔드포인트 JSON에 넣으세요.

자주 묻는 질문

어떤 AI 에이전트가 Apidog CLI를 구동할 수 있나요?

셸 명령을 실행할 수 있는 모든 에이전트가 가능합니다. Claude Code, Cursor, Codex 및 유사한 코딩 에이전트를 사용할 수 있습니다. CLI는 에이전트 종류보다 올바른 명령과 유효한 페이로드를 중요하게 봅니다.

유료 요금제가 필요한가요?

아니요. Apidog는 오픈 소스는 아니지만, 무료 등급과 apidog-cli를 사용하면 이 글에서 설명한 생성 및 게시 흐름을 사용할 수 있습니다.

에이전트가 기존 문서를 실수로 덮어쓸 수 있나요?

create는 새 리소스를 추가합니다. 기존 리소스를 수정하려면 update를 사용해야 하며, 별도의 안전장치가 필요합니다. 자세한 내용은 API 사양 업데이트 동반 가이드를 참고하세요.

일반적인 AI 문서 생성기와 무엇이 다른가요?

일반적인 AI 문서 도구는 코드에서 텍스트를 생성합니다. 이 방식은 팀이 관리하는 단일 라이브 소스에서 엔드포인트, 스키마, 가이드, 게시 사이트를 포함한 구조화된 문서를 생성합니다. 따라서 팀이 편집하는 API 정의와 문서가 어긋나는 문제를 줄일 수 있습니다.

마무리

Apidog CLI를 실행할 수 있는 에이전트는 사람들이 미루기 쉬운 문서화 작업을 처리할 수 있습니다. 엔드포인트를 만들고, 관련 가이드를 작성하고, 문서 사이트를 게시하는 작업이 모두 터미널 명령으로 연결됩니다.

신뢰할 수 있는 흐름의 핵심은 하나입니다.

스키마를 조회하고, 유효성을 검사한 뒤, 생성합니다.

에이전트에 이 루프, 앞서 제시한 규칙 블록, 프로젝트 ID를 제공하세요. 그러면 문서화 작업은 코드 뒤에 따라오는 수동 작업이 아니라, 검토 가능한 자동화 작업이 됩니다.

Apidog 다운로드 또는 Apidog CLI 전체 가이드에서 전체 명령 참조를 확인할 수 있습니다.

Top comments (0)