Apidog에서 코딩 없이 API 목킹하는 법

프런트엔드 팀의 작업이 지연되고 있습니다. `GET /users` 및 `GET /orders`에 대한 백엔드가 아직 준비되지 않았지만, UI는 목록을 렌더링하고, 페이지를 매기고, 빈 상태를 처리하기 위해 실제와 같은 데이터가 필요합니다. 예전 방식은 가짜 JSON 파일을 수동으로 작성하고 제공한 다음, 필드가 변경될 때마다 계속 수정하는 것이었습니다. 이 작업은 지루하며, 실제 API와 거의 즉시 동기화되지 않게 됩니다.

더 빠른 방법이 있습니다. API 사양이 이미 있다면, Apidog는 설정이나 코드 없이 엔드포인트 스키마에서 바로 작동하는 목(mock)을 생성할 수 있습니다. 이 기능은 스마트 목(Smart Mock)이라고 불리며, 필드 이름과 유형을 읽어 실제와 같은 데이터를 생성합니다. 예를 들어, `name` 필드는 그럴듯한 이름을 반환하고, `email` 필드는 그럴듯한 이메일을 반환합니다. 이 가이드는 두 가지 전자상거래 엔드포인트를 처음부터 끝까지 목업하는 방법을 안내하고, 목 URL이 어디에 있는지 보여주며, 어떤 응답이 우선순위를 갖는지 설명하고, 스마트 목이 잘못 추측할 때 어떻게 해야 하는지 다룹니다. 개념에 대한 더 넓은 개요를 먼저 원한다면, API 목업이란 무엇이며 어떻게 작동하는지에 대한 저희의 개요가 배경 지식을 제공하고, JSON 스키마 사이트에서는 스마트 목이 준수하는 제약 모델을 설명합니다.

버튼

스마트 목(Smart Mock)의 기능 및 시간 절약 효과

문서에 따르면 Apidog의 목 엔진은 다섯 가지 작업을 수행할 수 있습니다. API 사양에서 자동으로 생성된 데이터를 반환할 수 있으며, 이것이 스마트 목입니다. 사양에 정의된 응답 예시를 반환할 수 있습니다. 지정된 사용자 지정 응답을 반환할 수 있습니다. 요청 매개변수에 따라 다른 응답을 반환할 수 있으며, 이것이 조건부 목업입니다. 또한 목 스크립트를 통해 요청과 관련된 값을 가진 응답을 반환할 수 있습니다.

스마트 목은 해당 기능군 중 설정이 필요 없는 멤버이며, Apidog의 설계, 디버그 및 테스트 도구와 함께 내장되어 있습니다. 예시 본문을 정의하거나 규칙을 작성할 필요가 없습니다. 엔드포인트에 지정된 응답 스키마가 있는 한, 스마트 목은 해당 스키마를 읽고 모든 필드를 실제와 같은 값으로 채웁니다. 이는 자동 대체 기능으로 작동합니다. 미리 정의된 예시가 없는 엔드포인트도 합리적인 값을 반환하므로, 어떤 요청도 빈 응답으로 돌아오지 않습니다.

작업이 지연된 프런트엔드에게는 이것이 전부입니다. API를 한 번 가져오거나 설계하면, 모든 엔드포인트가 즉시 라이브 목이 됩니다. 스키마가 변경되면 목도 함께 변경됩니다. 둘 다 하나의 소스를 읽기 때문입니다.

시작하기 전에: 한 가지 필수 조건

스마트 목은 엔드포인트에 지정된 응답이 필요합니다. 이것이 유일한 전제 조건입니다. Apidog에서 API를 설계했다면, 엔드포인트의 응답 정의 아래에 응답 스키마를 추가하세요. OpenAPI 파일을 가져온 경우, 응답 스키마도 일반적으로 함께 제공됩니다. 정의된 응답이 없으면 엔진이 읽을 것이 없으므로, 목은 유용한 것을 반환하지 않습니다.

로컬 목을 사용할 계획이라면 Apidog 데스크톱 클라이언트도 필요합니다. 이는 자체 머신에서 실행되며 Apidog 웹에서는 사용할 수 없습니다. 따라하려면 Apidog를 다운로드하세요. 무료이며 신용카드가 필요 없습니다.

단계별: GET /users 및 GET /orders 목업

작은 상점 API를 위한 목업을 만들어 봅시다. 두 개의 엔드포인트를 정의하고 둘 다 호출할 것입니다.

1단계: 엔드포인트 및 응답 스키마 정의

다음과 같은 응답 본문으로 `GET /users`를 생성합니다.

{
  "id": 1024,
  "name": "Amara Osei",
  "email": "amara.osei@example.com",
  "phone": "+1-415-555-0148",
  "createdAt": "2026-03-11T09:24:00Z",
  "isActive": true
}

그런 다음 목록을 반환하는 `GET /orders`를 생성합니다.

[
  {
    "orderId": "ORD-58210",
    "userId": 1024,
    "total": 84.50,
    "currency": "USD",
    "status": "shipped",
    "createdAt": "2026-05-02T14:03:00Z"
  }
]

각 속성에 스키마에 유형이 있는지 확인하세요. 유형과 이름은 스마트 목이 적절한 값을 선택하는 데 사용하는 요소입니다.

2단계: 목 URL 찾기 및 복사

모든 엔드포인트에는 자동으로 목 URL이 할당됩니다. URL을 찾는 위치는 현재 모드에 따라 다릅니다.

DESIGN 모드에서는 엔드포인트 아래의 API 탭에 목 URL이 있습니다.
DEBUG 모드에서는 목 탭에 있습니다.

복사하려면 '클릭하여 복사'를 클릭하세요. 한 가지 주의할 점은, 이것은 URL만 복사한다는 것입니다. 엔드포인트가 GET 이외의 메서드를 사용하거나 요청 본문이 필요한 경우, 호출 시 메서드와 본문을 직접 추가해야 합니다.

로컬 목 URL은 `127.0.0.1` 포트 `4523`에서 실행되며, 경로 모드에서는 다음과 같습니다.

http://127.0.0.1:4523/m1/{projectID}-{versionNo}-{serverNo}/users

Apidog 클라이언트가 열려 있는 동안 로컬 목은 자동으로 시작됩니다. 또한 ID로 엔드포인트를 대상으로 하는 ID 모드 형식도 있습니다.

http://127.0.0.1:4523/m2/{projectID}-{versionNo}-{serverNo}/{endpointId}

3단계: 목 호출

curl로 URL을 호출합니다.

curl http://127.0.0.1:4523/m1/1234567-0-0/users

스키마에서 생성된 다음과 같은 응답을 받게 됩니다.

{
  "id": 3187,
  "name": "Diego Marchetti",
  "email": "diego.marchetti@example.net",
  "phone": "+1-628-555-0113",
  "createdAt": "2026-01-27T18:41:22Z",
  "isActive": true
}

`name`이 이름처럼 읽히고 `email`이 이메일처럼 읽히는 것을 확인하세요. 이것은 무작위적인 노이즈가 아니라 속성 이름 매칭(Property Name Matching)이 작동한 결과입니다. 요청을 새로 고치면 동적 값이 재생성되어 각 호출마다 새로운 데이터를 얻을 수 있습니다. 이는 UI가 다양한 콘텐츠를 어떻게 처리하는지 테스트하는 데 유용합니다.

동일한 방식으로 주문 엔드포인트를 호출합니다.

curl http://127.0.0.1:4523/m1/1234567-0-0/orders

실제와 같은 총계, 상태 및 타임스탬프를 가진 주문 객체 배열을 얻게 되며, 이는 주문 목록 보기에 사용할 준비가 된 것입니다.

스마트 목이 각 값을 결정하는 방법

스마트 목이 단일 속성을 채울 때, 세 가지 계층의 데이터 생성 우선순위에 따라 작동합니다. 이 순서를 이해하면 출력을 정확히 제어하는 방법을 알 수 있습니다.

목 필드. 응답 사양의 속성에 사용자 지정 값 또는 표현식을 설정하면, 이 값이 우선합니다. 목 필드는 두 가지 입력 유형을 가집니다. 항상 동일한 정적 값을 반환하는 고정 값(Fixed value)과 다양한 데이터를 생성하는 동적 표현식인 Faker 구문(Faker statement)입니다. 예를 들어, `status` 필드의 목 필드를 `shipped`, `pending`, `delivered` 중에서 선택하는 Faker 구문으로 설정할 수 있습니다.
속성 이름 매칭. 목 필드가 설정되지 않은 경우, 스마트 목은 와일드카드 또는 정규 표현식 패턴을 사용하여 속성 이름을 내장 규칙과 일치시킨 다음, 이에 맞는 데이터를 생성합니다. `email`과 `createdAt`이 올바르게 생성되는 이유가 바로 이것입니다. 규칙은 목 설정(Mock Settings) 아래에 있으며, 사용자 지정 규칙을 추가할 수 있습니다.
JSON 스키마. 이름이 어떤 규칙과도 일치하지 않으면, 스마트 목은 스키마에 의해 제약된 유형 기반 기본값으로 돌아갑니다. 일치하는 이름도 없고 제약 조건도 없는 문자열은 일반 문자열을 얻게 됩니다.

생성된 데이터는 문자열 길이, 열거형 값, 숫자 범위 및 배열 길이를 포함하여 전체적으로 JSON 스키마 제약 조건을 준수합니다. `status`를 세 가지 값의 열거형으로 설정하면, 스마트 목은 항상 그 세 가지 중 하나만 반환합니다. 배열의 `minItems`를 3으로 설정하면, 최소 세 개의 항목을 받게 됩니다. 모든 속성 설정은 최종 목 데이터에 나타납니다.

Apidog는 목 로케일도 지원하므로, 다양한 언어와 지역 형식으로 테스트 데이터를 생성할 수 있습니다. 상점이 일본 시장을 대상으로 하는 경우, 로케일을 전환하면 이름과 주소가 올바른 형식으로 반환됩니다.

스마트 목이 잘못 추측할 때와 이를 조정하는 방법

스마트 목은 추론 기반이므로 때로는 잘못 추측할 수도 있습니다. `sku`라는 속성이 내장 규칙과 일치하지 않아 일반 문자열로 대체될 수 있습니다. `total`이 두 자리 소수점과 합리적인 범위를 원했지만, 일반 숫자로 반환될 수도 있습니다. 가장 가벼운 터치부터 가장 많은 제어까지, 수정하는 방법은 다음과 같습니다.

스키마를 먼저 강화하세요. 종종 더 나은 제약 조건으로 문제가 해결됩니다. `status`에 `enum`을, `total`에 `minimum`과 `maximum`을, `sku`에 `pattern`을 추가하세요. 스마트 목은 이 모든 것을 준수하므로, 사용자 지정 값 없이도 출력이 범위 내로 정확히 맞춰집니다.
목 필드를 설정하세요. 스키마만으로 원하는 것을 표현할 수 없을 때, 속성의 목 필드를 설정하세요. `currency`가 `USD`와 같이 필드가 항상 동일한 값을 반환해야 할 때는 고정 값(Fixed value)을 사용하세요. 범위 내에서 다양성을 원할 때는 Faker 구문(Faker statement)을 사용하세요. Apidog의 Faker 레이어는 Mock.js 라이브러리와 동일한 아이디어를 기반으로 하며, Apidog에서 Faker를 사용하는 방법에 대한 저희 가이드에서 표현식 구문을 자세히 다룹니다.
속성 이름 매칭 규칙을 추가하세요. 동일한 잘못 명명된 필드가 여러 엔드포인트에 걸쳐 나타나는 경우, 스마트 목에게 한 번만 가르쳐주세요. 설정(Settings)으로 이동하여 일반 설정(General Settings), 기능 설정(Feature Settings), 목 설정(Mock Settings)으로 이동합니다. 새로 만들기(New)를 클릭하고 필드 이름과 일치하는 조건을 정의한 다음, 목 표현식을 제공합니다. 그러면 프로젝트 전체의 모든 `sku`가 일반 문자열 대신 정의한 패턴을 생성합니다.

목 우선순위 순서: 실제로 승리하는 것은 무엇인가

흔히 혼란스러운 점은 여러 응답이 가능할 때 엔드포인트가 어떤 응답을 반환하는지입니다. Apidog는 프로젝트 설정(Project Settings)의 목 설정(Mock Settings)에 있는 기본 목 메서드(Default mock method) 설정으로 이 문제를 해결합니다. 두 가지 옵션이 있습니다.

스마트 목 우선 (기본값)은 목 기대(Mock Expectation), 그 다음 스마트 목(Smart Mock) 순서로 적용됩니다.
응답 예시 우선은 목 기대(Mock Expectation), 그 다음 응답 예시(Response Example), 그 다음 스마트 목(Smart Mock) 순서로 적용됩니다.

왼쪽에서 오른쪽으로 읽으세요. 기본 설정에서 요청은 일치하는 목 기대(Mock Expectation)를 확인하고, 일치하는 것이 없으면 스마트 목이 본문을 생성합니다. 응답 예시 우선으로 전환하면, 스마트 목으로 대체되기 전에 정의된 응답 예시가 먼저 확인됩니다.

두 시퀀스 위에 하나의 규칙이 있습니다. 어떤 시퀀스를 선택했는지와 상관없이, 목 기대(Mock Expectation)는 구성되어 있고 조건이 일치하면 항상 최우선 순위를 가집니다. 따라서 `userId`가 `9999`일 때 `404`를 반환하는 조건부 응답을 설정하면, 기본 목 메서드(Default mock method)와 관계없이 해당 기대가 실행됩니다. 매개변수 기반 응답에 대한 자세한 내용은 Apidog에서 조건부 API 응답을 목업하는 방법에 대한 저희 가이드를 참조하세요.

실질적인 요약: 사용자 지정 목 기대(Mock Expectation)가 모든 것을 능가하며, 그 다음은 설정에 따라 스마트 목 또는 응답 예시입니다. 스마트 목은 항상 최후의 대체 수단이며, 이것이 모든 요청이 응답을 받는 이유입니다.

로컬, 클라우드, 러너 목: 목이 실행되는 곳

스마트 목과 사용자 지정 목은 응답이 어떻게 생성되는지를 설명합니다. 해당 목이 호스팅되는 위치는 별개의 선택 사항이며, Apidog는 세 가지 옵션을 제공합니다.

로컬 목은 Apidog 클라이언트를 통해 컴퓨터에서 실행됩니다. 자동으로 시작되며 클라이언트가 열려 있는 동안에만 접근할 수 있습니다. `127.0.0.1:4523`에서 수신하므로, 네트워크의 다른 장치에서는 머신의 LAN IP가 필요합니다. Apidog 웹에서는 사용할 수 없습니다.
클라우드 목은 Apidog 서버에서 호스팅되며 24시간 내내 접근할 수 있습니다. 기본적으로 꺼져 있으므로, 팀원이나 배포된 미리보기가 목에 접근하도록 하려면 환경 관리에서 켜세요. URL은 `https://mock.apidog.com`을 사용하며 동일한 `m1`/`m2` 경로 구조를 가지며, 프로덕션 트래픽이 아닌 테스트용입니다.
러너 목은 자체 팀 인프라에 자체 호스팅되며 팀 전체에 공유됩니다. 이는 목이 자체 네트워크 뒤에 존재해야 하는 내부 환경에 적합합니다.

단독 프런트엔드 작업에는 로컬 목을, 다른 사람이 접근해야 할 때는 클라우드 목을, 목이 자체 서버에 있어야 할 때는 러너 목을 선택하세요. 호스팅 옵션을 다른 서비스와 비교하고 있다면, 온라인 API 목업 도구 비교가 이들을 나란히 보여주고, Apidog 클라우드 목 가이드는 호스팅 설정에 대해 자세히 다룹니다.

알아두면 좋은 몇 가지 라우팅 주의사항

목 라우팅에는 사람들을 혼란스럽게 하는 몇 가지 규칙이 있습니다.

엔드포인트 경로는 `/`로 시작해야 합니다. `/orders`와 같은 경로는 목 환경을 통해 올바르게 라우팅됩니다. `/`로 시작하지 않는 완전한 URL은 목 환경을 전혀 사용하지 않으며, 선행 슬래시가 없는 경로는 ID 모드에서만 작동합니다.
두 API가 동일한 메서드와 경로를 공유하는 경우, 경로 모드만으로는 이들을 구분할 수 없습니다. 정확히 의도하는 엔드포인트를 가리키려면 `?apidogApiId={endpointId}` 쿼리 매개변수를 추가하세요.
그리고 새로 고침 동작을 기억하세요. 요청을 새로 고치면 목 데이터가 업데이트됩니다. 각 새로 고침은 동적 값을 재생성하므로, 동일한 응답을 두 번 본다면 새로운 호출이 아닌 캐시된 보기를 보고 있을 가능성이 높습니다.

Apidog CLI로 워크플로우 자동화

목업 자체는 Apidog의 GUI 및 클라우드 기능입니다. 로컬, 클라우드 또는 러너 중 어느 것이든 목 엔진이 응답을 제공합니다. Apidog CLI는 터미널에서 목 서버를 호스팅하거나 시작하지 않습니다. CLI가 추가하는 것은 프로젝트가 발전함에 따라 목업 뒤에 있는 스키마를 정확하게 유지하는 방법입니다.

스마트 목은 엔드포인트 스키마에서 출력을 생성하므로, 목업은 사양만큼만 좋습니다. Apidog CLI와 이를 통해 작동하는 Cursor, Claude Code, Trae, Codex와 같은 AI 코딩 에이전트는 프로젝트의 엔드포인트와 스키마를 생성하고 업데이트할 수 있습니다. 이를 통해 계약이 변경될 때마다 수동으로 필드를 편집하기 위해 앱을 열 필요 없이 목업 출력을 정확하게 유지할 수 있습니다.

그러면 목이 프런트엔드 작업을 해제한 후, 동일한 프로젝트의 테스트 시나리오가 CI에서 헤드리스로 실행되어 목이 설명한 동일한 계약에 대해 실제 백엔드를 확인합니다. 이는 단일 명령으로 이루어집니다.

apidog run -t <scenario_id> -e <env_id> -r html,cli

`npm install -g apidog-cli` (Node.js v16 이상)로 설치하고, `apidog login --with-token`으로 인증하면 어떤 파이프라인에도 연결할 수 있습니다. CI/CD 파이프라인에서 Apidog 실행에 대한 저희 가이드가 설정 과정을 안내합니다. 목은 프런트엔드 작업을 계속 진행시키고, CLI는 동일한 단일 진실 공급원에 대해 백엔드의 정직성을 유지합니다.

자주 묻는 질문

스마트 목을 사용하기 위해 코드를 작성해야 하나요? 아니요. 엔드포인트에 지정된 응답 스키마가 있는 한, 스마트 목은 실제와 같은 데이터를 자동으로 생성합니다. 특정 필드를 재정의하고 싶을 때만 코드, Faker 구문 또는 목 스크립트를 사용합니다. 개념에 대해서는 목 API 개요를 참조하세요.

내 목 URL이 아무것도 반환하지 않는 이유는 무엇인가요? 가장 흔한 원인은 엔드포인트에 응답 정의가 누락된 경우입니다. 스마트 목은 응답 스키마를 읽으므로, 먼저 하나를 추가하세요. 또한 경로가 `/`로 시작하는지 확인하고, 로컬 목을 사용하는 경우 Apidog 클라이언트가 열려 있는지 확인하세요.

스마트 목이 무작위 값 대신 특정 값을 반환하도록 하려면 어떻게 해야 하나요? 속성의 목 필드(Mock Field)를 설정하세요. 고정 값(Fixed value)은 항상 동일한 것을 반환하며, Faker 구문(Faker statement)은 다양하지만 제어된 데이터를 반환합니다. 목 필드는 스마트 목의 3단계 우선순위 중 가장 위에 있으므로, 이름 매칭과 스키마 기본값보다 항상 우선합니다.

팀원들이 내 노트북에서 실행되는 목에 접근할 수 있나요? 로컬 목은 `127.0.0.1:4523`에서 수신하므로, 로컬 네트워크를 통해서만, 그리고 Apidog 클라이언트가 열려 있는 동안에만 가능합니다. 항상 접근할 수 있도록 하려면, 기본적으로 꺼져 있고 `https://mock.apidog.com`에서 호스팅되는 클라우드 목을 켜세요.

예시와 스마트 목이 모두 있을 경우 어떤 응답이 우선하나요? 기본 목 메서드(Default mock method)에 따라 다릅니다. 스마트 목 우선(Smart Mock First) 설정에서는 스마트 목이 본문을 생성합니다. 응답 예시 우선(Response example first) 설정에서는 스마트 목 이전에 응답 예시가 사용됩니다. 어느 쪽이든, 일치하는 목 기대(Mock Expectation)는 둘 다 무시합니다.

마무리

스마트 목은 API 스키마를 코드나 설정 없이 작동하는 목으로 변환하며, 이는 작업이 지연된 프런트엔드에 정확히 필요한 것입니다. 응답을 정의하고, API 탭 또는 목 탭에서 목 URL을 복사하여 호출하세요. 추측을 조정해야 할 때는 스키마를 강화하거나 목 필드를 설정하고, 목 기대(Mock Expectation)가 항상 우선한다는 것을 기억하세요. Apidog를 다운로드하고 이 문장을 읽는 시간 안에 첫 번째 엔드포인트를 목업해보세요.

버튼