DEV Community

Cover image for CLI에서 API 모킹하는 방법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

CLI에서 API 모킹하는 방법

구축할 가짜 API가 필요합니다. 백엔드가 준비되지 않았거나, 서드파티 서비스에 속도 제한이 있거나, 라이브 서버에 접속하지 않고 테스트를 실행하고 싶을 때가 있습니다. 이때 일반적인 해결책은 목(mock)입니다. 핵심은 목을 재현 가능하고 자동화 가능하게 만드는 것입니다.

지금 Apidog를 사용해 보세요

GUI에서 라우트와 미리 정의된 응답을 클릭으로 설정할 수 있습니다. 한 번만 테스트한다면 충분할 수 있습니다. 하지만 데스크톱 앱에서 수동으로 만든 목은 재현과 버전 관리가 어렵고, CI 또는 AI 코딩 에이전트가 동일한 환경을 다시 만들 수 없습니다.

명령줄에서 정의하는 목은 다릅니다. 명령 자체가 스크립트, 파이프라인 단계, 에이전트가 실행할 수 있는 코드가 됩니다. 사람이 실행할 수 있는 명령은 CI와 자동화 도구도 실행할 수 있습니다.

이 가이드는 두 가지 경로를 다룹니다.

  1. 일반적인 오픈소스 경로: 파일에서 직접 실행하는 단일 바이너리 목 서버
  2. Apidog CLI 경로: 스펙을 가져오고, 호스팅된 목에 사용자 지정 기대값을 적용하는 방식

전체 도구 선택 기준은 최고의 API 목 도구 및 REST API 목킹 도구 가이드도 참고하세요.

일반적인 경로: 파일에서 목 서버 실행하기

고전적인 CLI 목 도구는 파일 하나를 로컬 HTTP API로 바꿉니다. OpenAPI 스펙 또는 JSON 데이터를 전달하면 로컬 포트에서 실제 엔드포인트를 제공합니다.

프로젝트 생성, 로그인, 계정 설정 없이 실행할 수 있습니다. 다음 세 가지 도구로 대부분의 상황을 처리할 수 있습니다.

Prism: OpenAPI 스펙 제공하기

이미 OpenAPI 파일이 있다면 Stoplight의 Prism을 사용할 수 있습니다. Prism은 paths, 응답 예시, 스키마를 읽어 계약에 맞는 응답을 반환합니다.

npx @stoplight/prism-cli mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

기본적으로 http://127.0.0.1:4010에서 서버가 시작됩니다.

다음 요청으로 동작을 확인할 수 있습니다.

curl http://127.0.0.1:4010/orders/123
Enter fullscreen mode Exit fullscreen mode

Prism의 동작 방식은 다음과 같습니다.

  • 응답에 example이 있으면 해당 예시를 반환합니다.
  • 예시가 없으면 스키마를 기반으로 유효한 무작위 응답을 생성합니다.
  • 들어오는 요청을 OpenAPI 스펙과 비교해 검증합니다.
  • 스펙에 맞지 않는 요청에는 422 응답을 반환합니다.
  • 상태 비저장(stateless)이므로 POST 요청 결과를 저장하지 않습니다.

전역 설치가 필요하다면 다음 명령을 사용하세요.

npm install -g @stoplight/prism-cli
Enter fullscreen mode Exit fullscreen mode

이후에는 npx 없이 실행할 수 있습니다.

prism mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Prism은 API 계약 검증이 중요하고, 상태를 유지할 필요가 없는 경우에 적합합니다.

Mockoon CLI: 데이터 파일을 헤드리스로 실행하기

Mockoon CLI는 Mockoon 데스크톱 앱에서 내보낸 환경 파일 또는 OpenAPI JSON/YAML 파일을 헤드리스 환경에서 실행합니다.

데스크톱 앱으로 라우트를 시각적으로 구성하고, CI 또는 서버에서는 CLI로 같은 환경을 실행할 수 있습니다.

npx @mockoon/cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

기본적으로 포트 3000에서 실행됩니다. 다른 포트를 사용하려면 --port를 추가하세요.

npx @mockoon/cli start --data ./env.json --port 8080
Enter fullscreen mode Exit fullscreen mode

--data에는 다음 파일을 지정할 수 있습니다.

  • Mockoon 환경 파일
  • OpenAPI JSON 파일
  • OpenAPI YAML 파일

이전 Mockoon 버전에서 생성된 파일을 사용해도 CLI는 원본 파일을 변경하지 않고 메모리에서 마이그레이션합니다.

전역 설치는 다음과 같습니다.

npm install -g @mockoon/cli
Enter fullscreen mode Exit fullscreen mode

설치 후에는 다음 명령을 사용할 수 있습니다.

mockoon-cli start --data ./env.json
Enter fullscreen mode Exit fullscreen mode

Mockoon CLI는 OpenAPI 스펙만으로는 부족한, 더 풍부하고 수동 조정된 라우트가 필요할 때 적합합니다. 관련 사례는 RESTful API를 위한 경량 목 서버에서도 확인할 수 있습니다.

json-server: JSON으로 REST API 가짜 만들기

아직 OpenAPI 스펙이 없다면 json-server가 가장 빠른 선택지입니다.

먼저 데이터를 담은 db.json 파일을 만듭니다.

{
  "posts": [
    {
      "id": "1",
      "title": "첫 번째 게시글",
      "published": true
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

그다음 서버를 실행합니다.

npx json-server db.json
Enter fullscreen mode Exit fullscreen mode

이제 http://localhost:3000/posts에서 다음 REST 작업을 사용할 수 있습니다.

  • GET /posts
  • POST /posts
  • PUT /posts/:id
  • PATCH /posts/:id
  • DELETE /posts/:id

예를 들어 새 데이터를 추가할 수 있습니다.

curl -X POST http://localhost:3000/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"새 게시글","published":false}'
Enter fullscreen mode Exit fullscreen mode

json-server는 POST 요청으로 생성한 레코드를 파일에 기록합니다. 따라서 Prism과 달리 상태 유지 동작을 테스트할 수 있습니다. 필터링, 정렬, 페이지네이션도 쿼리 파라미터로 처리할 수 있습니다.

전역 설치가 필요하다면 다음 명령을 사용하세요.

npm install -g json-server
Enter fullscreen mode Exit fullscreen mode

오픈소스 경로의 장점은 단순합니다. 각 도구는 파일 하나에서 실행되는 독립적인 서버입니다. 다만 목이 API 설계, 테스트, 문서와 분리될 수 있으므로 파일과 실행 프로세스는 직접 동기화해야 합니다.

정확한 요청 매칭이나 더 깊은 재현 기능이 필요하다면 MockServer와 WireMock도 고려할 수 있습니다. 다만 Java 런타임이 필요합니다.

Apidog CLI 경로: 스펙 가져오기, 기대값 스크립트 작성하기

Apidog의 목 방식은 로컬 CLI 목 서버와 다릅니다.

apidog CLI에는 다음과 같은 명령이 없습니다.

apidog mock ./openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog는 로컬에서 파일 기반 서버를 시작하지 않습니다. 대신 Apidog가 목을 호스팅하고, CLI는 스펙 가져오기와 사용자 지정 응답 기대값 관리를 담당합니다.

Apidog는 오픈소스가 아닌 상용 제품이며 무료 등급을 제공합니다. 이 경로의 핵심은 목, API 설계, 테스트가 별도의 파일과 프로세스가 아니라 하나의 프로젝트에서 같은 소스를 공유한다는 점입니다.

파일 하나로 일회성 목 서버만 필요하다면 Prism, Mockoon CLI, json-server가 더 가볍습니다. 반대로 목이 실제 API 변경 사항과 함께 관리되어야 한다면 Apidog CLI 흐름이 적합합니다.

먼저 CLI를 설치하고 인증합니다. 토큰 설정은 Apidog CLI 설치 가이드에서 확인할 수 있습니다.

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

스펙을 가져와 호스팅된 스마트 목 받기

먼저 API 정의를 프로젝트에 가져옵니다.

apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

가져오기가 완료되면 Apidog는 각 엔드포인트에 대한 호스팅된 목 URL을 생성합니다.

Prism이나 json-server와의 차이는 명확합니다.

  • 로컬 서버 프로세스를 시작하지 않습니다.
  • 스펙 가져오기를 통해 호스팅된 목을 생성합니다.
  • 스키마의 필드 이름과 타입을 기반으로 응답을 생성합니다.

예를 들어 email 필드는 이메일 형식의 값을, createdAt 필드는 타임스탬프 형식의 값을 반환합니다.

apidog import는 OpenAPI 외에도 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>
Enter fullscreen mode Exit fullscreen mode

명령 결과는 구조화된 JSON으로 반환됩니다. 필요하다면 jq로 ID를 추출해 후속 명령에 전달할 수 있습니다.

기대값을 조회, 수정, 삭제하는 명령은 다음과 같습니다.

apidog mock get --project <PROJECT_ID>
apidog mock update --project <PROJECT_ID> --file ./mock.json
apidog mock delete --project <PROJECT_ID>
Enter fullscreen mode Exit fullscreen mode

create와 update는 기대값을 정의한 JSON 파일을 --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
Enter fullscreen mode Exit fullscreen mode

권장 흐름은 다음과 같습니다.

  1. cli-schema get으로 필요한 JSON 구조를 확인합니다.
  2. 구조에 맞게 mock.json을 작성합니다.
  3. cli-schema validate로 파일을 검증합니다.
  4. 검증이 성공하면 mock create를 실행합니다.

유효성 검사가 실패하면 0이 아닌 종료 코드를 반환하므로, 잘못된 기대값이 프로젝트에 적용되기 전에 CI 파이프라인을 중단할 수 있습니다.

업데이트도 동일한 방식으로 처리합니다.

apidog cli-schema get mock-update
apidog cli-schema validate mock-update --file ./mock.json
apidog mock update --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

모든 명령은 JSON을 반환합니다. agentHints.nextSteps 블록은 다음에 실행할 명령을 안내하므로, 사람뿐 아니라 AI 코딩 에이전트가 순서를 따라가기에도 적합합니다.

전체 명령 그룹은 완전한 Apidog CLI 가이드에서 확인할 수 있습니다.

CI에 통합하기

CLI 목은 종료 코드와 텍스트 출력을 제공하므로 CI에 쉽게 통합할 수 있습니다.

Prism을 이용한 로컬 통합 테스트 예시는 다음과 같습니다.

# 백그라운드에서 Prism을 시작한 다음, 이를 대상으로 테스트 실행
npx @stoplight/prism-cli mock ./openapi.yaml &
PRISM_PID=$!

npm test

kill $PRISM_PID
Enter fullscreen mode Exit fullscreen mode

Apidog 흐름에서는 시작하거나 종료할 로컬 프로세스가 없습니다. 기대값을 검증하고 적용한 뒤, 테스트에서 호스팅된 목 URL을 호출하면 됩니다.

# 기대값이 올바른 형식인지 확인한 다음 적용
apidog cli-schema validate mock-create --file ./mock.json
apidog mock create --project <PROJECT_ID> --file ./mock.json
Enter fullscreen mode Exit fullscreen mode

두 방식 모두 버튼 클릭 없이 자동화할 수 있습니다. 스펙 중심 팀, CI 작업, AI 에이전트가 같은 명령으로 같은 목 환경을 만들 수 있다는 것이 CLI 목의 핵심입니다.

흔한 문제점

apidog mock이 서버를 시작할 것이라고 기대하는 경우

apidog mock은 로컬 서버를 시작하지 않습니다.

다음과 같은 명령은 사용할 수 없습니다.

apidog mock start
apidog mock serve
apidog mock ./file.yaml
Enter fullscreen mode Exit fullscreen mode

Apidog에서 호스팅된 목을 만들려면 먼저 스펙을 가져옵니다.

apidog import --project <PROJECT_ID> --format openapi --file ./openapi.json
Enter fullscreen mode Exit fullscreen mode

그다음 apidog mock으로 사용자 지정 기대값을 관리합니다.

파일 기반 로컬 프로세스가 필요하다면 Prism, Mockoon CLI 또는 json-server를 사용하세요.

쓰기 전에 스키마 검증을 건너뛰는 경우

apidog mock create와 apidog mock update는 --file을 받습니다. 파일 구조가 잘못되면 실패하거나 의도하지 않은 설정이 적용될 수 있습니다.

항상 다음 단계를 먼저 실행하세요.

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

명령 두 개가 추가되지만 디버깅 시간을 줄일 수 있습니다.

스펙이 부실해서 Prism 응답이 비어 보이는 경우

Prism의 응답 품질은 OpenAPI 스펙의 예시와 스키마 품질에 따라 달라집니다.

응답에 example이 없고 스키마가 모호하면 모호한 데이터를 받을 수 있습니다. 목 응답을 더 명확하게 만들려면 스펙에 구체적인 응답 예시를 추가하세요.

상태 비저장 도구에서 상태 유지를 기대하는 경우

Prism과 Apidog의 계약 기반 목은 쓰기 작업 결과를 유지하지 않습니다.

POST 이후 GET 요청에서 새 레코드를 반환해야 한다면 다음 중 하나를 사용하세요.

  • json-server
  • 원하는 응답을 직접 반환하도록 정의한 Apidog 기대값

마무리

CLI 기반 목킹은 클릭 중심 작업을 스크립트, 코드 리뷰, CI, AI 에이전트 실행 흐름으로 전환합니다.

오픈소스 경로에서는 다음 도구를 선택할 수 있습니다.

  • Prism: OpenAPI 스펙 기반 계약 목
  • Mockoon CLI: 헤드리스 환경 파일 또는 OpenAPI 기반 목
  • json-server: JSON 데이터 기반 상태 유지 REST API

Apidog 경로는 다르게 동작합니다. 스펙을 한 번 가져와 호스팅된 스마트 목을 만들고, apidog mock과 cli-schema 검증으로 사용자 지정 응답을 스크립트합니다.

파일 하나에서 일회성 서버를 실행하려면 오픈소스 도구를 선택하세요. 목이 API 설계 및 테스트와 같은 프로젝트에서 함께 관리되어야 한다면 Apidog를 다운로드하고 CLI를 설치해 자동화 가능한 목 환경을 구성하세요.

Top comments (0)