구축할 가짜 API가 필요합니다. 백엔드가 준비되지 않았거나, 서드파티 서비스에 속도 제한이 있거나, 라이브 서버에 접속하지 않고 테스트를 실행하고 싶을 때가 있습니다. 이때 일반적인 해결책은 목(mock)입니다. 문제는 이 목을 어떻게 세우느냐입니다.
GUI를 클릭하여 라우트와 미리 정의된 응답을 설정할 수 있습니다. 한 번은 괜찮습니다. 하지만 데스크톱 앱에서 수동으로 만든 목은 재현하기 어렵고, 버전을 관리하기 어려우며, CI 또는 AI 코딩 에이전트가 자체적으로 다시 만들 수 없습니다. 명령줄에서 정의하는 목은 다릅니다. 이는 스크립트의 명령어이자, 파이프라인의 단계이며, 에이전트가 실행할 수 있는 코드 한 줄입니다. 당신이 입력하는 것을 기계도 입력할 수 있습니다.
이 가이드는 두 가지 경로를 다룹니다. 첫째, 일반적인 오픈소스 경로: 파일에서 직접 실행하는 단일 바이너리 목 서버로, 하나의 명령으로 스펙 또는 JSON 파일이 라이브 엔드포인트가 됩니다. 다음으로, 작동 방식이 다르고 그 자체로 이해할 가치가 있는 Apidog CLI 경로입니다. 먼저 옵션들의 전체적인 흐름을 알고 싶다면, 최고의 API 목 도구와 REST API 목킹 도구 가이드 모두 더 넓은 시야를 제공할 것입니다.
일반적인 경로: 파일에서 목 서버 실행하기
고전적인 CLI 목은 파일을 지정하는 작은 바이너리입니다. 스펙 또는 데이터 파일을 제공하면 로컬 포트에서 실제 HTTP 엔드포인트를 제공합니다. 프로젝트, 로그인, 계정이 필요 없습니다. 이 도구들은 한 가지 일을 합니다: 파일을 호출할 수 있는 가짜 API로 변환하는 것입니다. 세 가지 도구가 거의 모든 경우를 다룹니다.
Prism: OpenAPI 스펙 제공하기
이미 OpenAPI 파일이 있다면, Stoplight의 Prism은 가장 적은 노력으로 실행할 수 있는 목입니다. 이는 paths, 예시, 스키마를 읽어 계약에 맞는 응답을 제공합니다.
npx @stoplight/prism-cli mock ./openapi.yaml
이는 스펙의 모든 작업을 연결하여 http://127.0.0.1:4010에서 서버를 시작합니다. Prism은 응답에 대해 정의한 example을 반환하거나, 정의하지 않았다면 스키마에서 유효한 무작위 응답을 생성합니다. 또한 들어오는 요청을 스펙에 대해 검증하여, 잘못된 호출에는 조용히 통과시키는 대신 적절한 422 응답을 반환합니다. 작동하는지 확인하려면 다음과 같이 호출하세요:
curl http://127.0.0.1:4010/orders/123
Prism은 상태 비저장(stateless)이므로, POST 요청은 아무것도 유지하지 않습니다. 이것은 목이 계약에 충실하기를 원할 때의 핵심입니다. 전역 설치를 위해서는 npm install -g @stoplight/prism-cli를 실행하고 npx를 생략합니다.
Mockoon CLI: 데이터 파일을 헤드리스로 실행하기
Mockoon CLI는 무료 Mockoon 데스크톱 앱에서 내보낸 데이터 파일이나 일반 OpenAPI 스펙 파일로부터 목을 실행합니다. 데스크톱 앱은 시각적으로 라우트를 구축할 수 있게 해주며, CLI는 동일한 환경을 CI 또는 서버에서 헤드리스로 실행합니다.
npx @mockoon/cli start --data ./env.json
--data를 Mockoon 환경 파일 또는 OpenAPI JSON/YAML 파일로 지정하면 즉시 포트 3000에서 기본적으로 서비스를 시작합니다. 변경하려면 --port를 추가하세요. 데이터 파일이 이전 Mockoon 버전에서 온 경우, CLI는 원본을 건드리지 않고 메모리에서 마이그레이션합니다. npm install -g @mockoon/cli를 사용하여 전역으로 설치하면 영구적인 mockoon-cli 명령을 사용할 수 있습니다. 이는 일반 스펙이 제공하는 것보다 더 풍부하고 수동으로 조정된 라우트를 원하면서도 GUI 없이 실행하고 싶을 때 적합합니다. RESTful API를 위한 경량 목 서버는 종종 이 범주에 속합니다.
json-server: JSON으로 REST API 가짜 만들기
아직 스펙이 없을 때, json-server가 가장 빠른 경로입니다. 데이터를 설명하는 일반 JSON 파일을 작성하면, 그 파일을 기반으로 완전한 REST API를 구축합니다.
npx json-server db.json
posts 배열을 포함하는 db.json 파일이 주어지면, 이는 http://localhost:3000/posts에 실제 GET, POST, PUT, PATCH, DELETE 작업을 제공합니다. POST는 실제로 레코드를 추가하고 파일에 다시 기록하므로, Prism에서는 얻을 수 없는 상태 유지 동작을 무료로 얻을 수 있습니다. 또한 쿼리 파라미터를 통해 필터링, 정렬, 페이지네이션 기능을 얻을 수 있습니다. PATH에 항상 포함되기를 원한다면 npm install -g json-server로 전역 설치하세요.
이것이 오픈 경로입니다. 각 도구는 단일 바이너리이며, 하나의 파일에서 실행되고 다른 것은 필요하지 않습니다. 단점은 각 도구가 독립적인 섬이라는 것입니다. 목은 실제 디자인, 테스트, 문서와 분리되어 존재하며, 파일과 실행 중인 프로세스를 직접 동기화해야 합니다. 정확한 요청 매칭이나 재현이 필요하다면, MockServer와 WireMock이 더 깊이 있는 기능을 제공하지만, Java 런타임이 필요합니다.
Apidog CLI 경로: 스펙 가져오기, 기대값 스크립트 작성하기
Apidog는 다르게 목을 만드는데, 이를 올바르게 이해하면 혼동을 줄일 수 있습니다. apidog CLI는 파일에서 로컬 목 서버를 시작하지 않습니다. apidog mock ./openapi.yaml과 같은 명령은 없습니다. 대신 Apidog가 목을 호스팅하며, CLI는 스펙을 제공하고 사용자 지정 응답을 스크립트하는 방법입니다.
먼저 솔직한 한마디입니다. Apidog는 오픈소스가 아니며, 무료 등급이 있는 상용 제품입니다. 이 무료 등급과 CLI를 통해 얻을 수 있는 것은 통합된 프로젝트로, 목, 디자인, 테스트가 세 개의 개별 파일과 세 개의 개별 프로세스 대신 하나의 진실된 소스를 공유한다는 것입니다. 하나의 파일에서 일회용 목만 필요하다면, 더 가벼운 도구가 좋습니다. 목이 실제 API 변경 사항과 일치해야 한다면 계속 읽어보세요.
먼저 설치 및 인증을 수행합니다(Apidog CLI 설치 가이드에서 토큰 설정 방법을 다룹니다):
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
스펙을 가져와 호스팅된 스마트 목 받기
첫 번째 단계는 API를 프로젝트에 가져오는 것입니다. OpenAPI 파일을 가져오면, Apidog는 모든 엔드포인트에 대한 목 URL을 자동으로 생성합니다.
apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
여기가 Apidog가 Prism 및 json-server와 다른 점입니다. 서버를 실행하지 않습니다. 가져오기 작업을 통해 각 작업에 대한 호스팅된 스마트 목을 얻습니다. 스마트 목은 스키마의 필드 유형과 이름을 읽어서, email 필드는 그럴듯한 이메일을 반환하고 createdAt은 무작위 문자열이 아닌 실제와 같은 타임스탬프를 반환합니다. apidog import는 또한 Swagger 2.0, Postman, Apidog 형식을 지원하므로, 기존 정의가 하나의 명령으로 라이브 목이 됩니다.
apidog mock으로 사용자 지정 응답 스크립트 작성하기
자동 생성된 목은 일반적인 경우를 다룹니다. 특정 요청에 대한 특정 응답, 예를 들어 한 사용자 ID에는 200, 다른 사용자 ID에는 404가 필요할 때 목 기대값을 추가합니다. 이것이 apidog mock 명령 그룹이 관리하는 것이며, 시작하는 서버가 아니라 이러한 기대값에 대한 CRUD 작업입니다.
apidog mock --help
apidog mock list --project <PROJECT_ID>
apidog mock list --project <PROJECT_ID> --http-api-id <ENDPOINT_ID>
목록은 구조화된 JSON을 반환하므로, jq를 통해 파이프하여 기대값의 ID를 찾아 다음 명령에 전달할 수 있습니다. 하나를 읽거나, 변경하거나, 제거하려면:
apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
create 및 update 서브커맨드는 기대값을 설명하는 --file 인수를 받습니다. 다음으로 다룰 내용인데, 작성하기 전에 형태를 올바르게 맞추십시오.
작성하기 전에 기대값 파일 유효성 검사하기
JSON을 손으로 추측하지 마십시오. CLI는 모든 쓰기 작업에 대한 스키마를 제공하므로, 실제 쓰기 전에 형태를 가져와 채우고 유효성을 검사합니다. 잘못된 형식의 기대값은 조용히 처리되는 대신 빠르게 실패합니다.
apidog cli-schema get mock-create
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
스키마를 가져와 mock.json을 일치하게 작성하고, 유효성을 검사한 다음 생성하십시오. 유효성 검사가 0이 아닌 종료 코드를 반환하면, 잘못된 파일이 프로젝트에 도달하기 전에 파이프라인이 중지됩니다. mock-update 스키마 키를 사용하여 업데이트에도 동일한 세 단계를 실행하십시오. 모든 명령은 JSON을 반환하며, agentHints.nextSteps 블록에는 당신 또는 에이전트에게 다음에 무엇을 실행해야 할지 알려주는 내용이 포함되어 있어, 이 흐름이 AI 코딩 도구뿐만 아니라 사람에게도 유용하게 사용될 수 있습니다. 완전한 Apidog CLI 가이드는 나머지 명령 그룹을 매핑합니다.
CI에 통합하기
모든 명령에 종료 코드와 텍스트 출력이 있기 때문에 두 경로 모두 파이프라인에 적합합니다. 동일한 작업에서 서버 기반 목과 통합 테스트는 다음과 같을 수 있습니다:
# 백그라운드에서 Prism을 시작한 다음, 이를 대상으로 테스트 실행
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!
npm test
kill $PRISM_PID
Apidog 흐름은 형태가 다릅니다. 목이 호스팅되기 때문에 시작하고 중지할 로컬 프로세스가 없습니다. 기대값을 설정 단계에서 검증하고 적용하며, 테스트는 호스팅된 목 URL을 직접 호출합니다.
# 기대값이 올바른 형식인지 확인한 다음 적용
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
어느 쪽이든, 아무도 버튼을 클릭하지 않습니다. CLI에서 목을 만드는 모든 이유가 바로 여기에 있습니다: 스펙 중심 팀, CI 작업, 그리고 AI 에이전트 모두 동일한 명령을 사용하여 동일한 가짜 API를 세울 수 있습니다.
흔한 문제점
apidog mock이 서버를 시작할 것이라고 기대하는 것. 그렇지 않습니다. apidog mock start, apidog mock serve, 또는 apidog mock ./file.yaml과 같은 명령은 없습니다. 스펙을 apidog import하여 호스팅된 목을 얻고, apidog mock은 그 위에 사용자 지정 기대값을 관리합니다. 파일에서 시작하는 로컬 프로세스를 원한다면, 그것은 Prism, Mockoon CLI 또는 json-server입니다.
쓰기 시 스키마 단계를 건너뛰는 것. apidog mock create 및 update는 --file 인수를 받으며, 잘못된 형태는 실패하거나 의도하지 않은 것을 기록합니다. 항상 cli-schema get 및 cli-schema validate를 먼저 실행하십시오. 두 개의 추가 명령이지만 디버깅 시간을 절약해 줍니다.
스펙이 부실하여 Prism이 비어 보이는 것. Prism의 목은 당신의 예시만큼만 좋습니다. 응답에 example이 없고 스키마가 모호하면, 모호한 데이터를 얻게 됩니다. 스펙에 예시를 추가하면 목이 더 명확해집니다.
상태 비저장 도구에서 상태 유지 기대값. Prism과 Apidog의 계약 목은 쓰기 작업을 유지하지 않습니다. POST 후 GET을 통해 새 레코드를 반환해야 한다면, json-server 또는 원하는 형태를 반환하는 Apidog 기대값을 사용하십시오.
마무리
CLI를 통한 목킹은 클릭 위주의 작업을 스크립트하고 검토하며 CI 또는 에이전트에 넘겨줄 수 있는 명령으로 바꿉니다. 오픈 경로는 파일에서 실행하는 단일 바이너리 서버를 제공합니다: OpenAPI 스펙을 위한 Prism, 헤드리스 데이터 파일을 위한 Mockoon CLI, JSON으로부터 즉석 REST API를 위한 json-server. Apidog 경로는 다른 방식으로 작동합니다. 스펙을 한 번 가져와 호스팅된 스마트 목을 얻은 다음, apidog mock 및 cli-schema 유효성 검사 가드를 사용하여 사용자 지정 응답을 스크립트합니다.
이미 가지고 있는 것과 목이 어디에 있어야 하는지에 따라 선택하십시오. 하나의 파일에서 일회용 서버를 원한다면 오픈 도구가 완벽합니다. 목이 하나의 프로젝트에서 디자인 및 테스트와 일치하기를 원한다면, Apidog를 다운로드하고 CLI를 설치하여 마우스 없이 목을 세우십시오.