DEV Community

Cover image for 무료 오픈소스 API 목킹 CLI 도구
Rihpig
Rihpig

Posted on • Originally published at apidog.com

무료 오픈소스 API 목킹 CLI 도구

명령줄에서 API를 모의(mock)할 때 라이선스는 기능 목록만큼 중요합니다. 소스를 직접 읽고, 자체 호스팅하고, 좌석 수 제한 없이 CI에서 실행할 수 있는 모의 서버는 로그인 뒤에 숨겨진 호스팅형 SaaS 모의 서버와 다릅니다. 이 가이드는 복제, 검사, 무료 실행이 가능한 오픈 소스 도구에 집중합니다.

지금 Apidog 사용해 보기

이 목록의 도구는 모두 MIT 또는 Apache-2.0 허용 라이선스로 소스가 공개되어 있고, 공개 GitHub 저장소에서 유지보수되며, 계정 없이 자체 호스팅할 수 있습니다. 시작 속도와 설치 크기를 우선하는 작은 단일 바이너리 도구를 찾는다면 경량 모의 서버 선택 사항을 참고하십시오. 이 글은 소스 공개와 자체 호스팅 가능 여부를 기준으로 하므로, 컨테이너 기반의 무거운 플랫폼도 포함합니다.

각 도구에서 다음을 확인합니다.

  • 라이선스와 저장소
  • 바로 실행 가능한 설치/실행 명령
  • 적합한 사용 사례
  • 도입 전 알아둘 제한 사항

상용 도구까지 포함한 비교가 필요하다면 최고의 API 모의 도구 종합과 REST API 모의 도구 개요를 참고하십시오.

참고: Apidog는 오픈 소스가 아닙니다. 이 글 마지막에서 통합형 대안으로만 다루며, 아래 6개 도구는 모두 오픈 소스입니다.

CLI 모의 도구를 오픈 소스로 만드는 기준

이 목록은 다음 세 가지 조건을 통과한 도구만 포함합니다.

  1. 허용 라이선스

    소스가 MIT 또는 Apache-2.0으로 공개되어야 합니다. 라이선스 비용이나 좌석 수 제한 없이 소스를 검토, 포크, 제품 내 배포할 수 있습니다.

  2. 자체 호스팅 가능

    노트북, Docker 컨테이너, 자체 서버에서 실행할 수 있어야 합니다. 호스팅된 제어 평면이나 계정 게이트 없이 에어갭(air-gapped) CI 러너에서도 실행할 수 있어야 합니다.

  3. 공개 유지보수

    커밋 히스토리, 이슈, 릴리스가 있는 공개 GitHub 저장소여야 합니다. GitHub Stars보다 최근 커밋과 태그된 릴리스를 우선 확인하십시오.

이 글의 기준은 원시 성능이나 설치 크기가 아닙니다. 그런 비교는 경량 모의 서버 가이드에서 다룹니다.

1. Prism (Stoplight)

Prism은 OpenAPI 또는 Postman 파일을 라이브 모의 서버로 전환합니다. 사양 파일의 예제 응답을 반환하고, 들어오는 요청을 스키마에 맞춰 검증하며, 실제 API 앞에서 유효성 검사 프록시로도 실행할 수 있습니다.

빠르게 실행하기 

npm install -g @stoplight/prism-cli

prism mock https://raw.githubusercontent.com/stoplightio/prism/master/examples/petstore.oas2.yaml
Enter fullscreen mode Exit fullscreen mode

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

curl http://127.0.0.1:4010/pets
Enter fullscreen mode Exit fullscreen mode

GET /pets 요청은 OpenAPI 문서에 정의된 예제를 반환합니다. 잘못된 요청 본문을 보내면 Prism은 위반된 스키마 조건을 알려줍니다.

이런 경우에 선택

  • OpenAPI 파일이 API 계약의 단일 진실 공급원인 경우
  • 스키마 기반 응답과 요청 검증이 필요한 경우
  • 실제 API와 사양의 차이를 프록시 단계에서 잡고 싶은 경우

제한 사항

  • 응답 품질은 사양의 예제와 스키마 품질에 의존합니다.
  • 생성 후 다시 조회하는 CRUD 같은 내장 상태 유지 동작은 없습니다.
  • Node.js 런타임이 필요합니다.

2. Mockoon CLI

Mockoon은 데스크톱 앱으로 널리 알려져 있지만, CLI는 CI와 자체 호스팅 환경을 위한 GUI 없는 실행 엔진입니다. 앱에서 만든 환경 파일을 실행하거나 OpenAPI 파일을 직접 입력으로 사용할 수 있습니다.

빠르게 실행하기 

npm install -g @mockoon/cli

mockoon-cli start --data ./environment.json --port 3000
Enter fullscreen mode Exit fullscreen mode

OpenAPI 파일을 직접 실행하려면 다음처럼 사용합니다.

mockoon-cli start --data ./openapi.yaml --port 3000
Enter fullscreen mode Exit fullscreen mode

개발 중 설정 파일 변경을 자동 반영하고 요청 로그를 출력하려면 옵션을 추가합니다.

mockoon-cli start \
  --data ./environment.json \
  --port 3000 \
  --watch \
  --log-transaction
Enter fullscreen mode Exit fullscreen mode

이런 경우에 선택

  • 코드 없이 조건부 응답 규칙을 구성하고 싶은 경우
  • 요청 헤더, 경로, 본문 조건에 따라 서로 다른 응답을 반환해야 하는 경우
  • 데스크톱 앱에서 설계하고 CI에서는 헤드리스로 실행하려는 경우
  • 프록시 모드와 응답 템플릿이 필요한 경우

제한 사항

  • 가장 편한 작성 방식은 데스크톱 앱입니다.
  • 환경 JSON을 직접 편집하면 관리가 까다로울 수 있습니다.
  • 동적 템플릿 문법을 별도로 익혀야 합니다.

3. json-server

json-server는 JSON 파일 하나로 REST API를 빠르게 구성하는 도구입니다. GET, POST, PUT, PATCH, DELETE CRUD 엔드포인트를 생성하며, 변경 내용은 JSON 파일에 기록됩니다.

빠르게 실행하기

먼저 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

이제 다음 요청을 바로 사용할 수 있습니다.

curl http://localhost:3000/posts
curl http://localhost:3000/posts/1

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

최상위 posts 배열을 기준으로 다음 CRUD 경로가 생성됩니다.

  • GET /posts
  • GET /posts/1
  • POST /posts
  • PUT /posts/1
  • PATCH /posts/1
  • DELETE /posts/1

필터링, 정렬, 페이지 매김도 쿼리 매개변수로 처리할 수 있습니다.

이런 경우에 선택

  • 백엔드 개발 전 프런트엔드 화면을 빠르게 연결해야 하는 경우
  • 생성한 데이터가 다음 요청에서도 유지되어야 하는 경우
  • 별도 설치 없이 npx로 즉시 실행하고 싶은 경우

제한 사항

  • REST 리소스 중심 구조를 전제하므로 임의의 API 형태를 정확히 재현하기 어렵습니다.
  • OpenAPI 가져오기를 지원하지 않습니다.
  • JSON 파일 자체가 계약이므로 스키마 검증 기능은 제한적입니다.
  • 부하 테스트나 프로덕션 수준 동작 재현에는 적합하지 않습니다.

4. WireMock

WireMock은 독립 실행형 HTTP 모의 서버입니다. JSON 관리 API 또는 스텁 파일로 요청 매칭, 응답 템플릿, 상태 기반 시나리오, 오류 주입, 프록시, 기록 및 재생을 설정할 수 있습니다.

빠르게 실행하기 

docker run -it --rm -p 8080:8080 wiremock/wiremock:latest
Enter fullscreen mode Exit fullscreen mode

다른 터미널에서 관리 API로 스텁을 등록합니다.

curl -X POST http://localhost:8080/__admin/mappings \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "method": "GET",
      "url": "/hello"
    },
    "response": {
      "status": 200,
      "body": "world"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

등록 후 응답을 확인합니다.

curl http://localhost:8080/hello
# world
Enter fullscreen mode Exit fullscreen mode

반복해서 사용할 스텁은 mappings/ 디렉터리에 JSON 파일로 저장하고 컨테이너에 마운트할 수도 있습니다.

이런 경우에 선택

  • 상태 전환이 필요한 복잡한 테스트 시나리오
  • 타임아웃, 지연, 5xx 오류 등 불안정한 외부 서비스를 재현하는 테스트
  • 실제 API 트래픽을 프록시로 캡처한 뒤 재생하는 워크플로
  • 모의 서버가 테스트 대상처럼 동작해야 하는 경우

제한 사항

  • JVM 기반이므로 Java 런타임 또는 컨테이너 환경이 필요합니다.
  • 단순 응답 하나를 모의하기에는 설정 범위가 넓게 느껴질 수 있습니다.
  • Prism처럼 사양 파일 하나를 바로 실행하는 단일 명령 중심 도구는 아닙니다.

5. MockServer

MockServer는 HTTP(S) 모의와 프록시 기능을 하나의 서버에서 제공하며, 통합 테스트에 초점을 둡니다. API 모의, 라이브 트래픽 프록시 및 기록, 오류 주입, 요청 검증을 지원합니다. 최근 버전에는 HTTP/2, gRPC, WebSocket 지원도 추가되었습니다.

빠르게 실행하기 

docker run -d --rm -p 1080:1080 mockserver/mockserver
Enter fullscreen mode Exit fullscreen mode

기대치(expectation)를 등록합니다.

curl -X PUT 'http://localhost:1080/mockserver/expectation' \
  -H 'Content-Type: application/json' \
  -d '{
    "httpRequest": {
      "path": "/order"
    },
    "httpResponse": {
      "body": "{\"status\":\"ok\"}"
    }
  }'
Enter fullscreen mode Exit fullscreen mode

이제 응답을 확인할 수 있습니다.

curl http://localhost:1080/order
# {"status":"ok"}
Enter fullscreen mode Exit fullscreen mode

Java, JavaScript, Ruby 등의 MockServer 클라이언트 라이브러리를 사용하면 curl 대신 테스트 코드에서 기대치를 등록할 수 있습니다.

이런 경우에 선택

  • 모의, 프록시, 오류 주입을 하나의 도구에서 처리해야 하는 경우
  • 특정 요청이 지정한 횟수만 발생했는지 검증해야 하는 경우
  • JVM 중심 테스트 스택을 사용 중인 경우
  • HTTP/2, gRPC, WebSocket까지 고려해야 하는 경우

MockServer가 맞지 않는다면 MockServer 대안도 비교해 보십시오.

제한 사항

  • WireMock과 마찬가지로 JVM 기반입니다.
  • 기대치 JSON이 길어질 수 있습니다.
  • WireMock과 기능이 겹치는 부분이 많으므로, 팀이 사용하는 클라이언트 라이브러리와 테스트 방식에 맞춰 선택하는 편이 좋습니다.

6. Microcks

Microcks는 단일 CLI 도구보다 플랫폼에 가깝습니다. CNCF 인큐베이팅 프로젝트이며, OpenAPI, AsyncAPI, gRPC, GraphQL, Postman 컬렉션, SoapUI 프로젝트를 라이브 모의로 전환합니다. 같은 계약을 사용해 실제 구현의 적합성 테스트도 실행할 수 있습니다.

빠르게 실행하기 

docker run -d --name microcks \
  -p 8585:8080 \
  quay.io/microcks/microcks-uber:latest
Enter fullscreen mode Exit fullscreen mode

브라우저에서 http://localhost:8585를 열고 API 사양을 가져오면 모의 엔드포인트를 만들 수 있습니다.

CI에서는 microcks-cli로 실행 중인 Microcks 서버를 제어합니다.

microcks-cli import 'petstore.yaml:true' \
  --microcksURL=http://localhost:8585/api \
  --keycloakClientId=... \
  --keycloakClientSecret=...
Enter fullscreen mode Exit fullscreen mode

이런 경우에 선택

  • 여러 API와 프로토콜을 중앙 카탈로그로 관리해야 하는 팀
  • 모의 서버와 계약 테스트를 함께 운영하려는 경우
  • HTTP뿐 아니라 이벤트 기반 또는 비동기 API를 모의해야 하는 경우
  • Kafka, MQTT 등 비동기 프로토콜을 다뤄야 하는 경우

제한 사항

  • 단일 바이너리가 아닌 서버 플랫폼입니다.
  • microcks-cli는 독립적으로 모의 서버를 제공하지 않습니다.
  • CLI는 실행 중인 Microcks 인스턴스에 테스트를 요청하고 아티팩트를 가져오는 클라이언트입니다.
  • 일회성 로컬 모의에는 Prism이나 json-server보다 무겁습니다.

솔직한 여담: Apidog

Apidog는 오픈 소스가 아니므로 위 6개 오픈 소스 도구와 같은 범주로 분류할 수는 없습니다. 다만 사양 기반 모의, 상태 유지 CRUD, 계약 테스트처럼 여러 도구가 나눠 해결하는 작업을 하나의 워크플로로 연결하고 싶다면 검토할 수 있습니다.

Apidog는 모의 기능을 포함한 무료 등급을 제공하는 프리미엄 플랫폼입니다. apidog-cli의 apidog mock을 사용하면 디자인, 테스트, 문서와 함께 하나의 프로젝트에서 터미널 기반 모의 기대치를 관리할 수 있습니다. 스마트 모의 기능은 스키마를 기반으로 필드 값을 생성하므로 예제 응답 본문을 매번 수동 작성하지 않아도 됩니다.

트레이드오프는 명확합니다.

  • 오픈 소스 및 에어갭 자체 호스팅이 필수라면 위의 6개 도구 중 하나를 선택하십시오.
  • 디자인-모의-테스트-문서화 흐름을 통합하는 것이 더 중요하다면 Apidog는 여러 도구를 연결하는 대안이 될 수 있습니다.

선택 방법

도구 가장 적합한 용도 설치 라이선스 참고
Prism 사양 기반 모의 및 유효성 검사 프록시 npm i -g @stoplight/prism-cli Apache-2.0 OpenAPI/Postman 입력, 무상태
Mockoon CLI 코드 없는 규칙 기반 응답 npm i -g @mockoon/cli MIT 앱에서 설계 후 헤드리스 실행
json-server 프런트엔드용 상태 유지 REST API npx json-server db.json MIT 영속성을 가진 CRUD, 제로 구성
WireMock 복잡한 테스트 시나리오와 오류 주입 docker run wiremock/wiremock Apache-2.0 JVM, 기록 및 재생, 상태 유지
MockServer 모의, 프록시, 요청 검증 docker run mockserver/mockserver Apache-2.0 JVM, HTTP/2, gRPC, WebSocket
Microcks 다중 API/프로토콜 카탈로그 docker run microcks-uber Apache-2.0 CNCF 플랫폼, CLI는 서버가 아닌 클라이언트
Apidog (OSS 아님) 통합 디자인-모의 워크플로 npm i -g apidog-cli 프리미엄 무료 등급, 하나의 프로젝트에서 apidog mock

인기도보다 필요한 모의 형태를 기준으로 선택하십시오.

  • OpenAPI 사양을 읽고 요청까지 검증해야 한다면: Prism
  • 백엔드 출시 전 상태 유지 CRUD가 필요하다면: json-server
  • 오류, 지연, 기록 및 재생이 포함된 테스트가 필요하다면: WireMock 또는 MockServer
  • 여러 프로토콜과 계약 테스트를 중앙 관리해야 한다면: Microcks
  • 시각적 설계와 규칙 기반 응답을 함께 사용하려면: Mockoon CLI

도구와 사용 사례를 더 구체적으로 매핑하려면 API 모의 사용 사례 가이드를 참고하십시오.

마무리

오픈 소스 CLI 모의 도구를 사용하면 소스를 검토하고, 자체 호스팅하며, CI에서 라이선스 비용 없이 모의 서버를 실행할 수 있습니다.

  • Prism과 json-server는 일반적인 로컬 모의 요구를 빠르게 해결합니다.
  • WireMock과 MockServer는 복잡한 통합 테스트 시나리오를 처리합니다.
  • Microcks는 여러 프로토콜과 계약 테스트를 포함한 관리형 카탈로그로 확장합니다.

이 글의 6개 도구는 모두 MIT 또는 Apache-2.0 라이선스이며, 공개 GitHub 저장소에서 확인할 수 있고 자체 호스팅할 수 있습니다.

별도 도구를 연결하지 않고 API 디자인, 테스트, 문서와 함께 모의를 관리하려면 Apidog를 다운로드하고 무료 등급에서 apidog mock을 사용해 볼 수 있습니다. 오픈 소스는 아니지만, 명령줄부터 CI까지의 API 워크플로를 한 곳에서 관리하는 선택지입니다.

Top comments (0)