DEV Community

Cover image for AI 에이전트가 Apidog CLI로 API 스펙을 업데이트하는 방법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

AI 에이전트가 Apidog CLI로 API 스펙을 업데이트하는 방법

API 스펙을 수동으로 편집하는 일은 작아 보여도 위험합니다. 필드 이름 변경, 열거형 값 추가, 필수 여부 조정은 모두 기존 엔드포인트와 참조 관계를 깨지 않도록 정확한 위치에 반영해야 합니다. 이런 반복적이고 정밀한 작업은 안전 장치가 갖춰져 있다면 AI 에이전트에 맡기기 적합합니다.

지금 Apidog 사용해 보기

Apidog CLI는 에이전트가 API 스펙을 안전하게 수정할 수 있는 워크플로를 제공합니다. 쓰기 전 스키마 유효성 검사, 격리된 AI 브랜치, 검토 가능한 병합 흐름을 조합하면 메인 브랜치에 직접 영향을 주지 않고 변경 사항을 검증할 수 있습니다.

이 글은 에이전트로 API 문서를 생성하는 방법의 후속 가이드입니다. 문서 생성은 대체로 추가 작업이지만, 기존 API 계약을 수정하는 작업은 호환성 문제와 데이터 손실 가능성이 있으므로 더 엄격한 절차가 필요합니다.

CLI에서 API 스펙 업데이트란?

Apidog 프로젝트의 스펙은 엔드포인트와 데이터 스키마로 구성됩니다. CLI에서 스펙을 변경하는 주요 방법은 다음 세 가지입니다.

  • endpoint update: 경로, 요청 파라미터, 응답 정의를 수정합니다.
  • schema update: 엔드포인트가 참조하는 데이터 모델을 수정합니다.
  • import: OpenAPI 파일 등 외부 스펙 파일을 가져와 프로젝트와 동기화합니다.

에이전트에게 이 작업을 맡기기 전에는 다음 두 가지를 반드시 이해해야 합니다.

  1. update는 부분 패치가 아니라 전체 교체입니다.
  2. 변경은 메인 브랜치가 아닌 AI 브랜치에서 수행해야 합니다.

가장 중요한 규칙: update는 전체 교체입니다

endpoint update와 schema update는 JSON Patch처럼 동작하지 않습니다. 전달한 일부 필드만 병합하는 것이 아니라, 전달한 구조를 기준으로 리소스를 교체합니다.

예를 들어 parameters 배열의 파라미터 하나만 바꾸려는 목적으로 해당 파라미터만 포함해 업데이트하면, 나머지 파라미터는 사라질 수 있습니다.

따라서 에이전트는 항상 다음 순서로 작업해야 합니다.

  1. 현재 리소스 전체를 가져옵니다.
  2. 가져온 전체 객체에서 필요한 부분만 수정합니다.
  3. 수정된 전체 객체를 스키마로 검증합니다.
  4. 검증된 전체 객체를 다시 업데이트합니다. 
# 1. 현재 엔드포인트 전체 조회
apidog endpoint get <endpointId> --project <projectId>

# 2. 전체 구조를 로컬에서 수정
# 변경하지 않는 필드는 유지합니다.

# 3. CLI 입력 스키마 조회 및 전체 객체 검증
apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file ./endpoint-full.json

# 4. 전체 객체를 다시 저장
apidog endpoint update <endpointId> \
  --project <projectId> \
  --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

에이전트 지침에는 다음 규칙을 명시적으로 넣으세요.

update 명령에 부분 객체를 전달하지 마십시오. 항상 전체 리소스를 조회하고, 전체 구조를 수정하고, 전체 객체를 다시 제출하십시오.

get 단계를 생략하면 기존 필드가 조용히 삭제될 수 있습니다. cli-schema validate를 먼저 실행하면 잘못된 페이로드가 프로젝트에 쓰이기 전에 로컬에서 실패합니다.

안전한 기본 흐름: AI 브랜치에서 작업하기

에이전트에 메인 브랜치 직접 편집 권한을 줄 수는 있지만, 처음부터 그렇게 운영하는 것은 권장하지 않습니다.

Apidog의 AI 브랜치는 에이전트 변경 사항을 격리하기 위한 브랜치입니다. 에이전트는 소스 브랜치에 영향을 주지 않고 리소스를 수정하고, 사람이 검토 및 승인을 완료할 때까지 변경 사항은 메인 브랜치에 반영되지 않습니다.

API 스펙용 풀 리퀘스트라고 생각하면 됩니다.

단계 1: AI 브랜치 만들기 

apidog branch create --project <projectId> --type ai \
  --from main \
  --name "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

브랜치 이름은 다음 규칙처럼 원본과 목적이 드러나도록 정하는 것이 좋습니다.

ai/YYYYMMDD-from-source-feature
Enter fullscreen mode Exit fullscreen mode

예시:

ai/20260713-from-main-refund-fields
Enter fullscreen mode Exit fullscreen mode

--from에는 메인 브랜치 또는 일반 스프린트 브랜치를 지정해야 합니다. 일반 브랜치를 소스로 지정하면 안 됩니다.

또한 원본과 차이가 없는 AI 브랜치는 24시간 후 자동 보관되므로, 완료되지 않은 실험 브랜치를 별도로 정리해야 하는 부담이 줄어듭니다.

단계 2: 수정할 기존 리소스를 AI 브랜치로 가져오기

AI 브랜치는 비어 있는 상태로 시작합니다. 소스 브랜치의 리소스가 자동으로 복제되지 않으므로, 기존 엔드포인트나 스키마를 수정하려면 먼저 pick-to로 가져와야 합니다.

apidog branch pick-to --project <projectId> --type ai \
  --from main \
  --to "ai/20260713-from-main-refund-fields" \
  --endpoint-ids <ids>
Enter fullscreen mode Exit fullscreen mode

이 단계가 필요한 경우는 다음과 같습니다.

  • 기존 엔드포인트를 수정할 때
  • 기존 스키마를 수정할 때
  • 기존 리소스를 삭제할 때

반대로 AI 브랜치에서 새로 생성하는 리소스에는 pick-to가 필요하지 않습니다.

단계 3: AI 브랜치에서 읽기-수정-쓰기 수행

이제 에이전트는 앞에서 설명한 읽기-수정-쓰기 루프를 실행합니다. 차이점은 모든 명령에 --branch를 지정한다는 점입니다.

# AI 브랜치의 엔드포인트 전체 조회
apidog endpoint get <endpointId> \
  --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields"

# 전체 객체를 검증한 뒤 AI 브랜치에 업데이트
apidog endpoint update <endpointId> \
  --project <projectId> \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

이 과정에서 메인 브랜치는 변경되지 않습니다. 에이전트가 잘못된 수정 작업을 하더라도 영향 범위는 해당 AI 브랜치로 제한됩니다.

단계 4: 변경 사항 검토 후 병합

AI 브랜치의 변경 사항은 자동으로 병합되지 않습니다. 에이전트가 작업을 끝내면 diff를 검토하고 병합 여부를 결정합니다.

apidog merge-request --help

apidog branch merge --project <projectId> --type ai \
  --from "ai/20260713-from-main-refund-fields" \
  --to main \
  --endpoint-ids <ids>
Enter fullscreen mode Exit fullscreen mode

메인 브랜치가 보호되어 있다면 직접 병합보다 병합 요청을 사용하세요. branch merge는 즉시 변경 사항을 적용하며, 소스와 대상 브랜치 모두에 대한 직접 편집 권한이 필요합니다.

보호된 메인 브랜치에서는 merge-request를 통해 요청을 만들고 Apidog 클라이언트에서 승인하는 흐름이 적합합니다.

실전 예시: amount를 amountCents로 변경하기

Refund 데이터 모델의 amount 필드를 amountCents로 바꾸고, 타입도 정수형으로 변경한다고 가정해 보겠습니다.

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

Refund 스키마의 amount 필드를 amountCents로 변경하고 타입을 정수형으로 바꾸십시오. 전체 스키마를 유지하고, AI 브랜치에서 검증 후 업데이트하십시오.

먼저 AI 브랜치에서 현재 스키마 전체를 가져옵니다.

apidog schema get <refundSchemaId> \
  --project $PID \
  --branch "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

가져온 전체 객체에서 jsonSchema를 수정합니다. 변경 대상이 아닌 필드는 그대로 유지해야 합니다.

{
  "name": "Refund",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amountCents"],
    "properties": {
      "orderId": { "type": "string" },
      "amountCents": { "type": "integer" },
      "reason": { "type": "string" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

여기서 핵심은 amountCents만 담긴 부분 객체를 보내지 않는 것입니다. schema update는 병합이 아니라 교체이므로, 기존 orderId, reason 등도 포함한 전체 스키마를 제출해야 합니다.

# 전체 스키마 객체 검증
apidog cli-schema validate schema-create --file ./refund-full.json

# 검증된 전체 객체를 AI 브랜치에 저장
apidog schema update <refundSchemaId> \
  --project $PID \
  --branch "ai/20260713-from-main-refund-fields" \
  --file ./refund-full.json
Enter fullscreen mode Exit fullscreen mode

그다음 AI 브랜치의 diff를 검토합니다.

확인할 항목은 간단합니다.

  • amount가 amountCents로 변경되었는가?
  • 타입이 integer로 변경되었는가?
  • 다른 속성은 의도치 않게 삭제 또는 변경되지 않았는가?
  • required 배열도 새 필드 이름을 반영하는가?

병합 전: 호환성을 깨는 변경 사항 분류하기

필수 필드 이름 변경은 호환성을 깨는 변경 사항입니다. 기존에 amount를 보내던 클라이언트는 이후 유효성 검사에 실패할 수 있습니다.

에이전트가 이런 변경을 조용히 병합하지 않도록, 프롬프트나 에이전트 정책에 다음 규칙을 넣으세요.

스펙 변경을 병합하기 전에 반드시 변경 유형을 분류하십시오.

- 호환 가능:
  새 선택 필드 추가, 새 엔드포인트 추가, 제약 조건 완화
  → 변경 내용을 요약하고 병합 요청을 생성합니다.

- 호환성 깨짐:
  필드 이름 변경 또는 삭제, 새 필수 필드 추가, 타입 강화, 제약 조건 강화
  → 즉시 중지합니다.
  영향을 받는 엔드포인트와 클라이언트 영향을 보고하고,
  사람의 명시적인 승인 전까지 병합하지 않습니다.
Enter fullscreen mode Exit fullscreen mode

AI 브랜치는 이 정책을 실제 검문소로 만들기 좋습니다. 변경 사항이 자동으로 메인 브랜치에 들어가지 않기 때문에, 에이전트가 “중지하고 보고”한 뒤 사람이 diff와 영향을 검토할 수 있습니다.

OpenAPI 파일로 스펙 업데이트하기

변경 사항이 이미 OpenAPI 파일에 있다면, 필드별 수정 대신 파일을 가져와 프로젝트와 동기화할 수 있습니다.

예를 들어 코드에서 OpenAPI 스펙을 생성했거나, 다른 팀에서 전달한 스펙 파일을 반영해야 하는 경우에 적합합니다.

apidog import --project <projectId> \
  --format openapi \
  --file ./openapi.json \
  --branch "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

import는 OpenAPI 3.x, Swagger 2.0, Postman 등의 형식을 지원합니다.

가져오기는 먼저 AI 브랜치에서 실행하세요. 그러면 외부 스펙의 변경 사항을 메인 브랜치에 반영하기 전에 검토할 수 있습니다.

병합 후에는 OpenAPI 파일을 다시 내보내 최종 결과를 확인할 수 있습니다.

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

사용 기준은 다음과 같습니다.

상황 권장 방식
Apidog가 스펙의 기준 저장소이고 일부 필드만 정밀하게 수정 endpoint update, schema update
코드 또는 외부 팀의 OpenAPI 파일이 기준 저장소 import
큰 변경 사항을 검토 가능한 단위로 반영 AI 브랜치에서 import 후 병합 요청

에이전트가 잘못 수정했을 때 롤백하기

AI 브랜치에서 작업하면 실수를 되돌리는 과정도 단순합니다.

에이전트가 원치 않는 변경을 만들었다면 메인 브랜치에는 아직 적용되지 않았으므로, AI 브랜치를 보관하면 됩니다.

apidog branch archive "ai/20260713-from-main-refund-fields" \
  --project <projectId> \
  --type ai
Enter fullscreen mode Exit fullscreen mode

승인된 diff가 없는 AI 브랜치는 24시간 후 자동 보관되기도 합니다.

메인 브랜치 직접 편집과 비교하면 차이가 명확합니다.

  • 메인 브랜치 직접 편집: 잘못된 변경이 즉시 반영되고 수동 복구가 필요할 수 있습니다.
  • AI 브랜치 편집: 잘못된 변경이 격리되며 브랜치 보관으로 폐기할 수 있습니다.

브랜치는 절차를 늘리는 장치가 아니라 API 스펙 변경을 위한 실행 취소 버튼입니다.

권한 문제 처리하기

update 또는 import 명령이 차단된다면 프로젝트에서 외부 AI 편집 권한이 꺼져 있을 수 있습니다.

이 경우 에이전트가 권한을 우회하려고 시도하게 하지 말고, 다음 선택지를 사람에게 제시하도록 하세요.

  1. AI 브랜치 기반 워크플로로 변경을 진행합니다.
  2. 프로젝트 설정에서 외부 AI 편집 권한을 활성화합니다.
  3. 에이전트는 변경 제안과 검증 결과만 만들고, 실제 반영은 사람이 수행합니다.

직접 편집을 허용하는 설정은 Apidog 클라이언트 2.8.32 이상에서 다음 경로에 있습니다.

프로젝트 설정 → 기능 설정 → AI 기능 설정
Enter fullscreen mode Exit fullscreen mode

일반적으로는 직접 편집보다 AI 브랜치 + 검토 병합 흐름이 더 안전합니다.

자주 발생하는 문제와 해결 방법

부분 업데이트로 기존 필드가 삭제됨

update는 병합이 아니라 교체입니다.

해결 방법

  1. get으로 전체 리소스를 조회합니다.
  2. 전체 객체를 수정합니다.
  3. cli-schema validate로 검증합니다.
  4. 전체 객체를 update로 다시 저장합니다.

AI 브랜치에서 기존 리소스를 찾을 수 없음

AI 브랜치는 비어 있는 상태로 시작합니다.

해결 방법

수정할 기존 리소스를 먼저 pick-to로 가져옵니다.

apidog branch pick-to --project <projectId> --type ai \
  --from main \
  --to "ai/20260713-from-main-refund-fields" \
  --endpoint-ids <ids>
Enter fullscreen mode Exit fullscreen mode

AI 브랜치 생성 시 --from 오류 발생

AI 브랜치의 소스는 메인 브랜치 또는 스프린트 브랜치여야 합니다.

해결 방법

--from에 일반 브랜치가 아닌 올바른 소스 브랜치를 지정합니다.

apidog branch create --project <projectId> --type ai \
  --from main \
  --name "ai/20260713-from-main-refund-fields"
Enter fullscreen mode Exit fullscreen mode

유효성 검사를 생략함

유효성 검사 없이 쓰기 작업을 수행하면 오타, 잘못된 타입, 누락된 필드가 프로젝트에 도달할 수 있습니다.

해결 방법

모든 update 전에 cli-schema validate를 실행합니다.

apidog cli-schema validate endpoint-create --file ./endpoint-full.json
Enter fullscreen mode Exit fullscreen mode

호환성을 깨는 변경을 자동 병합함

필수 필드 이름 변경, 필드 삭제, 타입 강화는 기존 클라이언트를 깨뜨릴 수 있습니다.

해결 방법

에이전트에 “호환성 깨짐 변경은 중지하고 사람 승인을 기다린다”는 정책을 부여합니다.

FAQ

에이전트가 메인 브랜치를 직접 편집하게 할 수 있나요?

외부 AI 편집 권한을 활성화하면 가능합니다. 하지만 처음에는 AI 브랜치에서 시작하는 것이 안전합니다. 사람이 병합을 승인하기 전까지 메인 브랜치에 변경 사항이 적용되지 않기 때문입니다.

직접 편집은 위험이 낮고 충분히 검증된 자동화에만 제한해서 사용하세요.

branch merge와 merge-request는 어떻게 다른가요?

branch merge는 변경 사항을 즉시 반영하며, 소스 및 대상 브랜치 모두에 대한 직접 편집 권한이 필요합니다.

merge-request는 검토 가능한 병합 요청을 생성합니다. 메인 브랜치가 보호되어 있다면 이 방식을 사용하는 것이 적합합니다.

에이전트가 Apidog 데스크톱 앱을 설치해야 하나요?

아니요. CLI는 독립적으로 실행됩니다.

다만 외부 AI 편집 권한을 설정하거나 변경해야 한다면 Apidog 클라이언트의 프로젝트 설정을 사용해야 합니다.

에이전트가 임의의 필드 이름을 추가하지 않게 하려면 어떻게 하나요?

cli-schema get과 cli-schema validate를 작업 절차에 포함하세요.

apidog cli-schema get schema-create
apidog cli-schema validate schema-create --file ./refund-full.json
Enter fullscreen mode Exit fullscreen mode

잘못된 구조나 지원하지 않는 필드가 포함된 페이로드는 프로젝트에 쓰기 전에 로컬 검증 단계에서 실패합니다.

마무리

AI 에이전트로 API 스펙을 안전하게 업데이트하려면 다음 세 가지 원칙을 지키면 됩니다.

  1. 메인 브랜치가 아닌 AI 브랜치에서 작업합니다.
  2. 모든 업데이트를 부분 패치가 아닌 전체 읽기-수정-쓰기 작업으로 처리합니다.
  3. 호환성을 깨는 변경은 사람이 검토하고 병합을 승인합니다.

Apidog CLI를 사용하면 이 과정을 스크립트화할 수 있습니다. 에이전트는 리소스를 조회하고, 전체 객체를 수정하고, 유효성을 검사하고, AI 브랜치에 변경 사항을 기록합니다. 사람은 최종 diff를 검토하고 병합 여부만 결정하면 됩니다.

Apidog를 다운로드한 뒤, 에이전트로 API 문서를 생성하는 워크플로와 함께 사용하면 API 스펙의 생성부터 유지 관리까지 일관된 자동화 흐름을 구축할 수 있습니다.

Top comments (0)