API 문서는 모두가 중요하다고 동의하지만 아무도 맡고 싶어 하지 않는 작업입니다. 새로운 엔드포인트가 출시되면 참조 문서가 일주일 늦게 업데이트되고, 시작하기 가이드에는 두 스플린트 전에 교체한 인증 흐름이 설명되어 있습니다. 이 작업은 실제적이지만 반복적이고 미루기 쉽습니다.
이러한 조합 (중요하고, 반복적이며, 미루기 쉬운)은 AI 에이전트가 잘하는 영역입니다. 에이전트가 터미널 명령을 실행할 수 있다면, 일반 언어 요청만으로 엔드포인트를 작성하고, 관련 설명 가이드를 작성하며, 문서 사이트를 게시할 수 있습니다. Apidog CLI는 이를 가능하게 합니다. 모든 문서화 작업은 에이전트가 읽고 실행할 수 있는 구조화된 JSON 출력을 가진 스크립트 가능한 명령입니다.
버튼
GUI나 MCP 서버가 아닌 CLI를 사용하는 이유
에이전트가 API 문서를 다룰 수 있는 세 가지 방법이 있으며, 각각 다른 문제를 해결합니다. 이 차이점을 정확히 이해하는 것이 도구와 씨름하는 것과 작업에 맞는 도구를 사용하는 것의 차이입니다.
| 접근 방식 | 방향 | 누가 주도하는가 | 검토 가능한 차이점? |
|---|---|---|---|
| GUI | 브라우저에서 사람이 편집 | 클릭하는 사람 | 아니요 |
| MCP 서버 | 사양을 읽고 코드 작성 | 편집기 내 에이전트 | 코드 리포에 있음, 문서에는 없음 |
| CLI | 문서 자체를 작성 | 터미널 내 에이전트 | 예, 모든 명령이 기록됨 |
MCP 서버는 에이전트가 API 정의를 읽고 그에 따라 클라이언트 코드를 생성하도록 할 때 탁월합니다. Cursor의 MCP를 통한 문서 흐름이 대표적인 예시입니다. 하지만 이것은 우리가 여기서 원하는 것과는 반대입니다. 우리는 에이전트가 문서를 생성하도록 하는 것입니다. 즉, 엔드포인트를 만들고, 마크다운 가이드를 작성하며, 사이트를 게시하는 것입니다.
이를 위해 CLI는 세 가지 측면에서 우월합니다. 첫째, 결정론적입니다. 동일한 명령은 동일한 결과를 생성합니다. 둘째, 스크립트 가능합니다. 전체 흐름을 CI에 통합할 수 있습니다. 셋째, 모든 호출에서 JSON을 반환하며, 에이전트에게 다음에 무엇을 할 수 있는지 알려주는 agentHints.nextSteps 필드를 포함합니다. 마지막 요점은 생각보다 중요합니다. 이는 에이전트가 다음 단계를 추측하는 것이 아니라 CLI의 자체 제안을 따른다는 의미입니다.
에이전트 환경 설정하기
CLI를 설치하고 한 번 인증합니다. 저희 설치 가이드에는 Node 버전 및 PATH가, 인증 가이드에는 토큰 및 CI 보안이 다루어져 있습니다.
npm install -g apidog-cli
apidog login --with-token <TOKEN>
Apidog 앱의 사용자 아바타 → 계정 설정 → API 접근 토큰에서 토큰을 가져옵니다. 로그인 후 로컬에 저장되므로 에이전트가 모든 호출에 토큰을 전달하지 않아도 됩니다.
모든 쓰기 작업은 프로젝트 ID에 대해 실행되며, 이 ID는 프로젝트 설정 → 기본 설정에서 찾거나 다음 명령을 실행하여 찾을 수 있습니다.
apidog project list
여기서 셸 명령을 실행할 수 있는 모든 코딩 에이전트(Claude Code, Cursor, Codex 등)가 작동합니다. CLI는 어떤 에이전트가 호출하는지 신경 쓰지 않습니다. 오직 명령과 페이로드가 올바른지 여부에만 신경 씁니다. 이는 전체를 신뢰할 수 있게 만드는 한 가지 규칙으로 이어집니다.
에이전트가 따라야 할 쓰기 의식
리소스를 생성하는 문서화 명령은 JSON 파일을 사용합니다. 에이전트는 이 JSON을 메모리에서 수동으로 생성해서는 안 됩니다. 모델이 임의로 생성한 필드 이름은 실패의 가장 큰 원인입니다. CLI는 모든 쓰기 작업에 대한 정확한 스키마를 제공하며, 올바른 순서는 항상 동일한 네 단계입니다.
# 1. CLI에 페이로드가 어떻게 생겼는지 물어봅니다.
apidog cli-schema get doc-create
# 2. 해당 스키마에서 JSON 파일을 생성합니다.
# 3. 쓰기 전에 유효성을 검사합니다 (로컬에서 누락된 필드를 잡아냅니다).
apidog cli-schema validate doc-create --file ./doc.json
# 4. 이제서야 실제 명령을 실행합니다.
apidog doc create --project <projectId> --file ./doc.json
이 루프를 에이전트의 지침에 포함시키십시오. 이는 "모델이 필드를 임의로 만들었다"는 문제를 "유효성 검사기가 내 컴퓨터에서 이를 거부했다"로 바꾸어, 클린 실행과 빌드 실패 사이의 차이를 만들어냅니다. 다음은 에이전트의 시스템 프롬프트 또는 CLAUDE.md / .cursorrules 파일에 직접 붙여넣을 수 있는 규칙 블록입니다.
Apidog CLI 규칙:
- JSON 페이로드를 직접 작성하지 마십시오. 먼저 `apidog cli-schema get `를 실행하고 해당 스키마를 기반으로 만드십시오.
- 모든 생성 또는 업데이트 전에 `apidog cli-schema validate --file `로 모든 파일의 유효성을 검사하십시오.
- 쓰기 명령 시 항상 `--project `를 전달하십시오.
- 다음 명령을 선택하기 위해 각 JSON 응답에서 `agentHints.nextSteps` 필드를 읽으십시오.
- 쓰기 작업이 권한으로 인해 차단된 경우, 작업을 중단하고 사람에게 문의하십시오. 해결책을 찾으려 하지 마십시오.
이 다섯 줄은 문서를 안정적으로 배포하는 에이전트와 페이로드를 추측하다가 막히는 에이전트를 구분하는 기준입니다.
1단계: 엔드포인트와 스키마에서 참조 생성
Apidog에서 API 참조는 프로젝트의 엔드포인트 및 데이터 스키마에서 생성됩니다. 따라서 에이전트의 첫 번째 작업은 이를 생성하는 것입니다. 다음과 같이 지시한다고 가정해 봅시다.
"주문 ID와 금액을 받는 POST /refunds 엔드포인트를 추가하고, 성공 및 유효성 검사 오류 응답을 문서화하세요."에이전트는 재사용 가능한 데이터 모델을 먼저 생성한 다음, 이를 참조하는 엔드포인트를 생성합니다. apidog cli-schema get schema-create를 실행하면 데이터 스키마가 name과 표준 jsonSchema 객체를 필요로 한다는 것을 알 수 있습니다. 따라서 에이전트는 refund-schema.json과 같은 것을 작성합니다.
{
"name": "Refund",
"description": "An order에 대해 발행된 환불",
"jsonSchema": {
"type": "object",
"required": ["orderId", "amount"],
"properties": {
"orderId": { "type": "string" },
"amount": { "type": "number" },
"reason": { "type": "string" }
}
}
}
유효성 검사 및 생성:
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json
이제 엔드포인트입니다. endpoint-create 스키마는 method와 path를 필요로 하며, #/definitions/{schemaId} 형식의 $ref를 사용하여 방금 만든 데이터 모델을 참조할 수 있게 합니다. 에이전트는 refunds-endpoint.json을 작성합니다.
{
"name": "환불 생성",
"method": "post",
"path": "/refunds",
"status": "developing",
"requestBody": {
"type": "application/json",
"jsonSchema": { "$ref": "#/definitions/<refundSchemaId>" }
}
}
apidog cli-schema validate endpoint-create --file ./refunds-endpoint.json
apidog endpoint create --project <projectId> --file ./refunds-endpoint.json
이제 /refunds에 대한 참조 문서가 팀이 편집하는 동일한 정의에서 렌더링되어 존재합니다. 참조 문서를 위한 별도의 "문서 내보내기" 단계는 없습니다. 엔드포인트가 등록되는 즉시 프로젝트에 실시간으로 반영됩니다. 이것이 스키마 우선 소스의 장점입니다. 참조 문서는 스키마 그 자체이므로 어긋날 수 없습니다.
2단계: 참조뿐만 아니라 가이드 작성
스키마에서 생성된 참조는 좋은 문서화의 절반에 불과합니다. 나머지 절반은 설명서입니다. 시작하기 페이지, 인증 안내서, 마이그레이션 노트 등이 있습니다. Apidog에서는 이들이 프로젝트의 문서 트리에 마크다운 문서로 존재하며, doc 명령 그룹에 의해 관리됩니다.
doc-create 스키마는 name만 필요로 합니다. content는 마크다운을 담고, folderId는 문서의 위치(0은 루트)를 지정합니다. 따라서 에이전트가 작성한 퀵스타트는 quickstart.json이 됩니다.
{
"name": "퀵스타트: 첫 환불",
"content": "# 퀵스타트\n\n이 가이드는 API 키부터 첫 환불까지 5분 안에 안내합니다...",
"folderId": 0
}
apidog doc list --project <projectId>
apidog cli-schema validate doc-create --file ./quickstart.json
apidog doc create --project <projectId> --file ./quickstart.json
이것이 바로 에이전트가 제 역할을 하는 부분입니다. "새로운 개발자를 위해 API 키부터 첫 환불까지 안내하는 퀵스타트를 작성해"라고 요청하면, 에이전트가 마크다운을 초안하고, 스키마가 기대하는 페이로드로 래핑하여 유효성을 검사한 다음 문서를 생성합니다. 브라우저도, 복사 붙여넣기도 필요 없습니다. 콘텐츠가 단순한 문자열 필드이기 때문에 에이전트는 작업에 필요한 만큼 길거나 상세한 가이드를 작성할 수 있습니다.
3단계: 문서 사이트 게시
참조 및 가이드가 준비되면 에이전트는 터미널에서도 게시할 수 있습니다. 두 개의 명령 그룹이 이 작업을 처리하며, 한 가지 명명 규칙이 사람들을 끊임없이 혼란스럽게 합니다.
doc: 프로젝트의 API 트리 내부에 있는 마크다운 문서 (2단계에서 생성한 것).docs-site: 호스팅되는 공개 문서 사이트.shared-doc: 전체 사이트가 아닌, 파트너에게 전달할 수 있는 공유 링크.
apidog docs-site list --project <projectId>
apidog cli-schema get docs-site-create
apidog docs-site create --project <projectId> --file ./docs-site.json
터미널에서 정의된 공개 사이트를 원할 때는 docs-site를 사용하고, 단순히 누군가에게 보낼 링크가 필요할 때는 shared-doc를 사용하세요. 둘 다 명령이므로, 게시가 모든 문서 변경 후 에이전트가 실행하는 스크립트 단계가 됩니다. 명령이 반환되는 순간 호스팅된 사이트에 업데이트가 반영됩니다.
4단계 (선택 사항): 휴대용 복사본 내보내기
때로는 문서를 파일로 원할 수 있습니다. 다른 곳에서 호스팅할 HTML 페이지, 정적 사이트 생성기를 위한 마크다운, 또는 하위 시스템에 전달할 OpenAPI 파일 등이 있습니다. export 명령은 이 세 가지를 모두 생성합니다.
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
프로젝트에 여러 서비스가 있고 그 중 일부만 문서화하고 싶다면, apidog export --help를 통해 출력을 좁히는 --scope, --api-ids, --folder-ids 플래그를 확인할 수 있습니다. 이런 식으로 하나의 프로젝트에서 서비스당 하나의 문서 파일을 배포할 수 있습니다.
완벽한 전체 예시
여기 일반 언어 요청과 이를 만족하기 위해 에이전트가 실행하는 명령을 포함한 전체 루프가 있습니다.
당신: "POST /refunds와GET /refunds/{id}가 포함된 결제 서비스를 새로 추가했습니다. 두 가지를 모두 문서화하고, 멱등 키에 대한 짧은 가이드를 작성한 다음, 문서 사이트에 게시하세요."
에이전트는 규칙에 따라 다음을 실행합니다.
# 공유 데이터 모델 생성
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json
# 두 엔드포인트 모두 생성
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json
# 마크다운 문서로 멱등성 가이드 작성
apidog doc create --project $PID --file ./idempotency-guide.json
# 게시
apidog docs-site create --project $PID --file ./docs-site.json
결과적인 차이점을 검토하면, 결제 서비스가 문서화되어 라이브 상태가 됩니다. 한때는 오후 내내 컨텍스트 전환을 해야 했던 작업이 이제 요청과 검토만으로 끝납니다.
에이전트 루프 또는 CI에 연결하기
모든 단계가 명령이기 때문에 전체 흐름을 CI나 에이전트의 작업 루프에 넣을 수 있습니다. 푸시할 때마다 마크다운 참조를 재생성하고 커밋하는 최소한의 단계는 다음과 같습니다.
- 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
CLI를 사용하여 에이전트를 처음부터 끝까지 실행하는 더 자세한 내용은 PRD에서 테스트 루프까지 및 완벽한 API를 구축하기 위해 5개의 AI 에이전트를 설정하는 방법을 참조하십시오. 두 경우의 패턴은 여기서와 동일합니다. 의도를 설명하고, 에이전트가 이를 검증된 CLI 호출로 변환하도록 한 다음, 결과를 검토하는 것입니다.
권한 참고 사항
에이전트를 통해 프로젝트에 쓰는 것은 게이트될 수 있습니다. create 명령이 차단되면 프로젝트에서 해당 브랜치에 대해 외부 AI 편집 권한이 꺼져 있는 것입니다. 두 가지 정직한 옵션이 있습니다. 프로젝트 설정 → 기능 설정 → AI 기능 설정(Apidog 클라이언트 2.8.32 이상)에서 직접 편집 권한을 활성화하거나, 에이전트가 격리된 AI 브랜치에서 작업하고 병합 요청을 여는 것입니다. API 사양 업데이트에 대한 동반 가이드는 AI 브랜치 흐름을 자세히 설명하며, 에이전트가 보호된 브랜치에서 문서를 생성할 때도 동일하게 적용됩니다.
일반적인 문제
에이전트가 JSON을 직접 만들었습니다. 이것이 가장 큰 실패 원인입니다. 에이전트가 추측한 스키마가 아닌 실제 스키마를 사용하도록 cli-schema get → cli-schema validate → create를 에이전트 지침에 강제하십시오.
누락된 프로젝트 ID. 모든 doc, docs-site, export 호출에는 읽기 가능한 프로젝트 이름이 아닌 설정의 ID인 --project가 필요합니다. 대부분의 "오류 발생" 보고는 이 때문입니다.
doc, docs-site, shared-doc 혼동. 이들은 세 가지 다른 것입니다. 트리 안의 마크다운 페이지, 호스팅된 사이트, 공유 링크입니다. 에이전트가 작성하기 전에 작업이 무엇을 의미하는지 확인하도록 하십시오.
CI에 토큰이 설정되지 않았습니다. apidog login은 토큰을 실행하는 머신에 저장합니다. 새 CI 러너에는 토큰이 없으므로, 어떤 명령이든 실행하기 전에 동일한 작업에서 login --with-token을 실행하고 토큰을 비밀(secret)로 유지하십시오.
아무것도 가리키지 않는 $ref. 엔드포인트가 #/definitions/{schemaId}로 데이터 모델을 참조할 때, 해당 스키마가 먼저 존재해야 합니다. 스키마를 사용하는 엔드포인트를 만들기 전에 스키마를 생성하십시오.
자주 묻는 질문
어떤 AI 에이전트가 Apidog CLI를 구동할 수 있나요? 셸 명령을 실행할 수 있는 모든 에이전트, 즉 Claude Code, Cursor, Codex 및 유사한 코딩 에이전트입니다. CLI는 에이전트 독립적입니다. 올바른 명령과 유효한 페이로드만 필요합니다.
유료 요금제가 필요한가요? 아니요. Apidog는 오픈 소스는 아니지만, 무료 등급과 apidog-cli를 사용하면 여기서 설명된 생성 및 게시 흐름을 사용할 수 있습니다.
에이전트가 실수로 기존 문서를 덮어쓸 수 있나요? create는 새로운 리소스를 추가합니다. 기존 리소스를 수정하려면 update를 사용하는데, 이는 다르게 작동하며 자체적인 안전장치가 필요합니다. 이에 대해서는 API 사양 업데이트 동반 가이드에 설명되어 있습니다.
이것이 AI 문서 생성기와 어떻게 다른가요? 일반적인 AI 문서 도구는 코드에서 텍스트를 생성합니다. 이것은 팀이 편집하는 내용과 어긋나지 않는 단일 라이브 소스에서 API 플랫폼(엔드포인트, 스키마, 가이드 및 게시된 사이트) 내에 구조화된 문서를 생성합니다.
마무리
Apidog CLI를 실행할 수 있는 에이전트는 사람들이 항상 미루는 문서화 작업을 처리할 수 있습니다. 즉, 엔드포인트를 생성하고, 관련 가이드를 작성하며, 사이트를 게시합니다. 이 모든 작업은 일반 언어 요청만으로 가능하며, 스키마 유효성 검사가 모든 쓰기 작업을 보호합니다. 귀하의 역할은 문서를 작성하는 것에서 차이점을 검토하는 것으로 바뀝니다.
이를 신뢰할 수 있게 만드는 한 가지 규칙은 쓰기 의식입니다. 스키마를 가져오고, 유효성을 검사한 다음 생성하는 것입니다. 에이전트에 이 루프와 위에 있는 다섯 줄 규칙 블록, 그리고 프로젝트 ID를 제공하면 문서화는 더 이상 코드 뒤에 따라오는 번거로운 작업이 아닙니다. CLI를 얻으려면 Apidog를 다운로드하거나, 전체 명령 참조를 보려면 Apidog CLI 전체 가이드를 읽어보십시오.
버튼