Rihpig

Posted on Jul 13 • Originally published at apidog.com

API 목킹을 위한 최고의 경량 CLI 툴

개발용 가짜 API가 필요하고, 30초 안에 실행해야 한다면 호스팅 서비스, Docker Compose 스택, GUI가 필요하지 않을 수 있습니다. 파일 하나를 읽어 localhost에서 응답을 시작하는 CLI 명령이면 충분합니다.

지금 Apidog 사용해 보기

경량 목(Mock) 서버는 OpenAPI 사양 또는 작은 데이터 파일을 입력으로 받아 실제 백엔드가 준비되기 전까지 프런트엔드와 테스트가 사용할 엔드포인트를 제공합니다. 대부분은 단일 바이너리 또는 npx로 실행되며, 설정 없이 빠르게 시작합니다. 반대로 JVM 기반 도구는 시작 비용이 더 크지만 정교한 요청 매칭과 상태 기반 테스트에 적합합니다.

이 글에서는 설치 부담이 적은 CLI 목 서버 6가지를 사용 목적별로 정리합니다. 먼저 npx만으로 실행할 수 있는 도구를 살펴보고, 정밀 제어가 가능한 JVM 서버와 Apidog CLI 기반 워크플로까지 다룹니다. GUI 및 호스팅 옵션도 함께 비교하려면 최고의 API 목 도구 종합을 참고하세요.

CLI 목 도구가 “경량”인 이유

경량성은 기능 수보다 설치와 실행에 드는 마찰이 적다는 뜻입니다. 도구를 선택할 때는 다음 항목을 확인하세요.

설치 크기와 런타임: npx로 실행하는 Node 패키지는 전역 설치가 필요 없습니다. JVM 서버는 일반적으로 Java 런타임과 JAR 파일이 필요합니다.
시작 속도: 로컬 개발에서는 명령 실행 후 바로 요청을 보낼 수 있어야 합니다. Node 기반 도구는 보통 빠르게 시작합니다.
첫 응답까지 필요한 설정: 파일 하나와 명령 하나로 엔드포인트를 만들 수 있는지 확인하세요.
터미널 우선 워크플로: 계정, 대시보드, GUI 없이 파일과 명령만으로 실행할 수 있으면 셸 스크립트와 CI에 쉽게 통합할 수 있습니다.

아래 도구는 빠르게 실행할 수 있는 순서로 정리했습니다. Prism, Mockoon CLI, json-server는 전역 설치 없이 npx로 시작할 수 있습니다.

Prism (Stoplight)

Prism은 OpenAPI 파일을 즉시 목 서버로 변환합니다. 이미 API 사양이 있다면 가장 적은 설정으로 계약 기반 목을 만들 수 있습니다. paths, examples, 스키마를 읽어 사양에 맞는 응답을 제공합니다.

npx @stoplight/prism-cli mock ./openapi.yaml

명령을 실행하면 사양의 작업을 연결하고 기본적으로 http://127.0.0.1:4010에서 서버를 시작합니다.

Prism 사용 시 다음을 확인하세요.

OpenAPI 파일에 응답 example을 정의합니다.
예시가 없으면 Prism은 스키마를 기준으로 유효한 임의 응답을 생성합니다.
요청은 사양에 대해 검증됩니다. 사양에 맞지 않는 호출은 조용히 통과하지 않고 적절한 422 응답을 받습니다.

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

npm install -g @stoplight/prism-cli
prism mock ./openapi.yaml

가장 적합한 경우: OpenAPI 계약을 기준으로 프런트엔드와 테스트용 목을 유지하려는 사양 우선 팀.

Prism은 Apache-2.0 라이선스이며 OpenAPI 3.1, 3.0, 2.0과 Postman 컬렉션을 지원합니다.

한계점: Prism은 상태 비저장 도구입니다. POST 요청을 보내도 데이터가 유지되지 않으므로 생성 후 조회하는 흐름을 그대로 재현할 수 없습니다. 응답 품질도 사양의 예시에 의존합니다. 계약 정확성이 중요하다면 REST API 목 도구 워크플로와 함께 사용하기 좋습니다.

Mockoon CLI

Mockoon CLI는 Mockoon 데스크톱 앱에서 내보낸 환경 데이터 파일이나 일반 OpenAPI 사양을 읽어 목 API를 실행합니다. GUI에서 경로를 설계하고, CI 또는 서버에서는 동일한 환경을 헤드리스로 실행하려는 경우에 적합합니다.

npx @mockoon/cli start --data ./mockoon-env.json --port 3000

--data에 Mockoon 환경 파일 또는 OpenAPI JSON/YAML 파일을 지정하면 바로 서버가 실행됩니다.

실행 절차는 간단합니다.

Mockoon 환경 파일 또는 OpenAPI 파일을 준비합니다.
--data 옵션으로 파일 경로를 지정합니다.
필요하면 --port로 포트를 변경합니다.
CI에서는 동일한 명령을 실행해 목 환경을 재사용합니다.

이전 Mockoon 버전에서 생성한 데이터 파일도 CLI가 원본 파일을 수정하지 않고 메모리에서 마이그레이션합니다. 전역 명령이 필요하면 다음을 사용하세요.

npm install -g @mockoon/cli
mockoon-cli start --data ./mockoon-env.json --port 3000

가장 적합한 경우: GUI에서 목 API를 설계하되, 배포와 CI에서는 헤드리스 실행이 필요한 팀.

Mockoon CLI는 MIT 라이선스이며 배포용 공식 Docker 이미지를 제공합니다.

한계점: 풍부한 경로 설정은 데스크톱 앱에서 구성하는 흐름에 최적화되어 있습니다. JSON 환경 파일을 직접 대규모로 편집하려면 관리가 까다로울 수 있습니다. GUI 없이 파일 하나만 직접 관리하고 싶다면 Prism이나 json-server가 더 단순합니다.

json-server

json-server는 OpenAPI 사양이 아직 없을 때 가장 빠르게 REST API를 만드는 방법입니다. 데이터 구조를 일반 JSON 파일로 작성하면 GET, POST, PUT, PATCH, DELETE를 포함한 REST API를 생성합니다.

echo '{ "posts": [{ "id": 1, "title": "hello" }] }' > db.json
npx json-server db.json

이제 http://localhost:3000/posts에서 CRUD API를 사용할 수 있습니다.

예를 들어 새 게시물을 추가하려면 다음 요청을 보낼 수 있습니다.

curl -X POST http://localhost:3000/posts \
  -H "Content-Type: application/json" \
  -d '{ "title": "new post" }'

POST /posts 요청은 실제로 레코드를 추가하고 db.json에 다시 기록합니다. 따라서 Prism이나 WireMock이 기본 설정으로 제공하지 않는 상태 저장 CRUD 흐름을 빠르게 구현할 수 있습니다.

또한 쿼리 파라미터를 사용해 필터링, 정렬, 페이지네이션을 적용할 수 있습니다. 1.x 버전은 기본적으로 파일을 감시하고 변경 시 다시 로드합니다.

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

npm install -g json-server
json-server db.json

가장 적합한 경우: 실제 API가 구현되기 전에 1분 안에 동작하는 REST 백엔드가 필요한 프런트엔드 개발자.

json-server는 MIT 라이선스이며, 사양 없이 시작할 수 있는 RESTful API용 경량 목 서버 옵션입니다.

한계점: 리소스 중심 REST 패턴을 전제로 합니다. 매우 커스텀한 경로, 비 REST 엔드포인트, 엄격한 헤더 매칭에는 적합하지 않습니다. 계약 검증 도구보다는 프로토타이핑 도구로 사용하는 편이 좋습니다.

MockServer

MockServer는 정밀한 요청 매칭이 필요한 통합 테스트에 적합합니다. 사양이나 데이터 파일을 제공하는 대신, 요청 조건과 응답 동작을 기대(expectation)로 직접 정의합니다.

다음 명령으로 포트 1080에서 서버를 시작합니다.

java -jar mockserver-netty-5.15.0-no-dependencies.jar -p 1080

MockServer에서는 다음 요소를 기준으로 요청을 매칭할 수 있습니다.

HTTP 메서드
경로
헤더
쿼리 파라미터
요청 본문

응답에는 지연과 실패 조건도 설정할 수 있으므로 타임아웃, 재시도, 오류 처리 테스트에 유용합니다.

Node 환경에서는 JAR 파일 대신 공식 래퍼를 사용할 수 있습니다.

npm install mockserver-node

const mockserver = require('mockserver-node');

mockserver.start_mockserver({ serverPort: 1080 });

가장 적합한 경우: 요청 형식과 응답 조건을 세밀하게 제어해야 하는 통합 테스트.

MockServer는 Apache-2.0 라이선스이며 단일 포트에서 HTTP, HTTPS 등을 지원합니다.

한계점: JVM 서버이므로 Node 기반 도구보다 무겁고 시작 시간이 길 수 있습니다. 기대 설정도 OpenAPI 파일을 지정하는 방식보다 장황합니다. 단순히 사양 기반 목이 필요하다면 과도한 선택일 수 있습니다. 다른 선택지를 비교하려면 MockServer 대안을 참고하세요.

WireMock (독립 실행형)

WireMock은 Java 및 JVM 테스트 환경에서 널리 사용하는 목 서버입니다. 독립 실행형 JAR는 JUnit 테스트에 내장하는 엔진과 같은 엔진을 사용하므로, 로컬 개발용 목과 테스트 스위트용 목을 같은 방식으로 관리할 수 있습니다.

java -jar wiremock-standalone.jar --port 8080

명령을 실행하면 포트 8080에서 서버가 시작됩니다.

WireMock은 다음 방식으로 스텁을 관리합니다.

mappings/ 디렉터리의 스텁 매핑 JSON 파일 사용
JSON API로 런타임 스텁 구성
실제 트래픽 기록 후 스텁으로 재생

특히 제어할 수 없는 타사 API를 테스트할 때 기록 및 재생 기능이 유용합니다. CI 환경에서는 공식 wiremock/wiremock Docker 이미지를 사용할 수 있습니다.

가장 적합한 경우: 로컬 개발과 JVM 테스트 스위트에서 하나의 목 엔진을 공유하고, 트래픽 기록 및 재생이 필요한 팀.

WireMock은 Apache-2.0 라이선스입니다.

한계점: MockServer와 마찬가지로 Java 런타임이 필요하고 Node 기반 도구보다 시작이 느립니다. 스텁 매핑 JSON은 강력하지만 단일 JSON 데이터 파일보다 학습할 내용이 많습니다. JavaScript 중심 환경이라면 Mock Service Worker(MSW) 대안 비교도 확인해 보세요.

Apidog CLI

앞의 도구는 각각 목킹의 특정 부분에 집중합니다. Apidog는 API 설계, 목, 테스트, 문서를 하나의 프로젝트에서 관리하고, Apidog CLI로 해당 프로젝트를 터미널에서 제어하는 통합 워크플로를 제공합니다.

Apidog는 오픈 소스가 아닌 무료 티어를 제공하는 상업 제품입니다. 별도 목 서버, 테스트 러너, 사양 도구를 조합하는 대신 하나의 프로젝트 단위로 관리하려는 경우 대안이 될 수 있습니다.

Apidog에서는 정의한 엔드포인트를 기준으로 스마트 목을 자동 생성합니다. 스키마 필드 타입과 이름 규칙을 따르므로, 예를 들어 phone 필드는 임의 문자열 대신 그럴듯한 전화번호 형식의 값을 반환합니다. 특정 요청에 특정 응답이 필요하면 목 기대(mock expectation)를 추가해 제어할 수 있습니다.

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog mock --help

CLI 사용 흐름은 다음과 같습니다.

apidog-cli를 설치합니다.
토큰으로 로그인합니다.
apidog mock --help로 목 명령 그룹을 확인합니다.
스크립트 또는 CI에서 프로젝트의 목 기대를 관리합니다.

CLI에는 목 외에도 엔드포인트, 스키마, 환경, 테스트 실행을 위한 명령 그룹이 포함됩니다. 출력은 agentHints.nextSteps 필드를 포함하는 구조화된 JSON 형식입니다. 전체 명령은 Apidog CLI 완전 가이드에서 확인할 수 있습니다.

가장 적합한 경우: 목, 사양, 테스트를 별도 도구로 나누지 않고 하나의 프로젝트에서 관리하려는 팀.

Apidog 다운로드 후 자신의 프로젝트에서 내장 목 서버와 CLI를 사용할 수 있습니다.

한계점: 단일 목적 바이너리가 아니라 플랫폼이므로 프로젝트와 로그인이 필요합니다. 단일 파일로 임시 목만 빠르게 만들고 싶다면 json-server 같은 도구가 더 가볍습니다. 이미 Apidog에서 API를 설계하고 있다면 목도 같은 프로젝트에서 관리할 수 있습니다.

선택 방법

현재 보유한 산출물을 기준으로 선택하면 됩니다.

도구	가장 적합한 경우	설치	오픈 소스?	참고
Prism	OpenAPI 사양을 목으로 제공	`npx @stoplight/prism-cli`	예 (Apache-2.0)	계약 정확성, 상태 비저장, 기본 포트 4010
Mockoon CLI	GUI로 구축한 목을 헤드리스 실행	`npx @mockoon/cli`	예 (MIT)	환경 파일 또는 OpenAPI 읽기, Docker 이미지
json-server	JSON에서 즉시 REST API 생성	`npx json-server`	예 (MIT)	상태 저장 CRUD, 사양 불필요, 기본 포트 3000
MockServer	정밀한 요청 매칭	`java -jar mockserver-netty-*.jar`	예 (Apache-2.0)	JVM, npm 래퍼 사용 가능, 기본 포트 1080
WireMock	JVM 개발과 테스트에서 엔진 공유	`java -jar wiremock-standalone.jar`	예 (Apache-2.0)	기록 및 재생, Docker 이미지, 기본 포트 8080
Apidog CLI	목, 사양, 테스트를 하나의 프로젝트에서 관리	`npm install -g apidog-cli`	아니요 (무료 티어)	자동 스마트 목과 관리형 기대

빠르게 결정하려면 다음 기준을 사용하세요.

OpenAPI 사양이 있다면: Prism 또는 Mockoon CLI
사양 없이 데이터만 있다면: json-server
헤더, 본문, 지연까지 정밀하게 검증해야 한다면: MockServer 또는 WireMock
목과 API 설계, 테스트를 함께 관리하려면: Apidog CLI

속도가 우선이면 npx 도구를 선택하고, 정밀 매칭이 필요하면 JVM 서버를 사용하세요. 여러 도구를 조합하는 대신 하나의 워크플로를 원한다면 Apidog가 적합합니다. 목킹 적용 여부를 결정하는 단계라면 API 목킹 사용 사례도 참고할 수 있습니다.

마무리

경량 목킹 도구를 고르는 기준은 간단합니다. 이미 무엇을 가지고 있는지 확인하세요.

사양이 있으면 Prism 또는 Mockoon CLI
빈 JSON 데이터에서 시작하면 json-server
엄격한 요청 매칭이 필요하면 MockServer 또는 WireMock
설계와 테스트 옆에서 목을 관리하려면 Apidog

이 여섯 도구는 모두 터미널에서 실행할 수 있고 CI 작업에 통합할 수 있으며, 몇 시간 대신 몇 초 안에 가짜 API를 제공합니다. 현재 요구를 해결하는 가장 작은 도구부터 선택하고, 실제로 필요해질 때만 더 많은 기능을 추가하세요.

통합 워크플로를 사용하려면 Apidog 다운로드 후 API 설계부터 목 서버 생성까지 한 프로젝트에서 시작해 보세요.

DEV Community