DEV Community

Cover image for Apidog에서 코딩 없이 API 목킹하는 법
Rihpig
Rihpig

Posted on • Originally published at apidog.com

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

프런트엔드 팀의 작업이 지연되고 있습니다. GET /users와 GET /orders 백엔드는 아직 준비되지 않았지만, UI에서는 목록 렌더링, 페이지네이션, 빈 상태, 에러 상태를 검증할 데이터가 필요합니다. JSON 파일을 수동으로 만들고 필드 변경 때마다 고치는 방식은 빠르게 실제 API 계약과 어긋납니다.

지금 Apidog 사용해 보기

API 사양이 이미 있다면 Apidog의 스마트 목(Smart Mock)으로 응답 스키마에서 실제와 유사한 데이터를 바로 생성할 수 있습니다. name은 이름처럼, email은 이메일처럼 생성됩니다. 이 글에서는 GET /users와 GET /orders를 목업하고, 목 URL을 호출하며, 응답 우선순위와 생성 결과를 제어하는 방법을 다룹니다. 개념이 필요하다면 API 목업의 동작 방식과 JSON Schema를 먼저 참고하세요.

스마트 목(Smart Mock)으로 할 수 있는 일

Apidog의 목 엔진은 다음 방식으로 응답을 반환할 수 있습니다.

  1. 스마트 목: 응답 스키마를 기반으로 데이터를 자동 생성
  2. 응답 예시: API에 정의한 예시 응답 반환
  3. 사용자 지정 응답: 직접 작성한 응답 반환
  4. 조건부 목업: 요청 파라미터에 따라 다른 응답 반환
  5. 목 스크립트: 요청 값과 연동된 동적 응답 반환

Apidog 목 기능 화면

스마트 목은 별도 예시 본문이나 규칙 없이 시작할 수 있는 방식입니다. 엔드포인트에 응답 스키마만 정의되어 있으면 필드명, 타입, 스키마 제약 조건을 읽어 데이터를 채웁니다.

예를 들어 다음과 같이 동작합니다.

  • name → 실제 이름 형식의 문자열
  • email → 이메일 형식의 문자열
  • createdAt → ISO 8601 날짜 문자열
  • isActive → 불리언 값
  • status + enum → 지정한 상태 값 중 하나

스키마가 변경되면 목 응답도 같은 소스에서 생성되므로 함께 변경됩니다. 프런트엔드와 백엔드가 같은 계약을 기준으로 작업할 수 있다는 점이 핵심입니다.

시작 전 필수 조건: 응답 스키마

스마트 목이 동작하려면 엔드포인트에 응답 정의와 응답 스키마가 있어야 합니다.

  • Apidog에서 API를 직접 설계했다면 응답 정의에 스키마를 추가합니다.
  • OpenAPI 파일을 가져왔다면 일반적으로 응답 스키마도 함께 가져옵니다.
  • 응답 정의가 없으면 스마트 목이 생성할 구조도 없습니다.

로컬 목을 사용하려면 Apidog 데스크톱 클라이언트가 필요합니다. 로컬 목은 Apidog 웹이 아니라 사용자 머신에서 실행됩니다.

Apidog 다운로드

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

작은 쇼핑몰 API를 예시로 두 엔드포인트를 정의하고 로컬 목 URL로 호출해 보겠습니다.

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
}
Enter fullscreen mode Exit fullscreen mode

그다음 GET /orders를 만듭니다.

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

각 속성에 타입을 명확히 지정하세요. 스마트 목은 타입뿐 아니라 필드 이름도 참고해 데이터를 생성합니다.

가능하면 스키마 제약 조건도 함께 설정하세요.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": ["pending", "paid", "shipped", "delivered"]
    },
    "total": {
      "type": "number",
      "minimum": 1,
      "maximum": 10000
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

2. 목 URL 찾기

Apidog는 엔드포인트별로 목 URL을 자동 생성합니다.

  • DESIGN 모드: 엔드포인트 아래 API 탭에서 확인
  • DEBUG 모드: Mock 탭에서 확인

클릭하여 복사를 사용하면 URL을 복사할 수 있습니다. 단, URL만 복사되므로 POST, PUT, PATCH처럼 요청 본문이 필요한 API는 호출할 때 메서드와 본문을 직접 지정해야 합니다.

로컬 목의 경로 모드 URL 형식은 다음과 같습니다.

http://127.0.0.1:4523/m1/{projectID}-{versionNo}-{serverNo}/users
Enter fullscreen mode Exit fullscreen mode

엔드포인트 ID를 직접 사용하는 ID 모드 형식도 있습니다.

http://127.0.0.1:4523/m2/{projectID}-{versionNo}-{serverNo}/{endpointId}
Enter fullscreen mode Exit fullscreen mode

로컬 목은 Apidog 클라이언트가 실행 중일 때 자동으로 시작됩니다.

3. 목 API 호출

GET /users를 호출합니다.

curl http://127.0.0.1:4523/m1/1234567-0-0/users
Enter fullscreen mode Exit fullscreen mode

응답은 다음과 같이 스키마 구조를 유지하면서 동적으로 생성됩니다.

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

새로 호출하면 동적 값이 다시 생성될 수 있습니다. 따라서 긴 이름, 다른 이메일 도메인, 여러 상태값 등 다양한 데이터를 UI에 노출해 볼 수 있습니다.

이제 주문 목록도 호출합니다.

curl http://127.0.0.1:4523/m1/1234567-0-0/orders
Enter fullscreen mode Exit fullscreen mode

프런트엔드는 이 응답을 실제 API 응답처럼 사용해 목록, 금액 포맷, 상태 배지, 날짜 표시를 구현할 수 있습니다.

스마트 목이 값을 생성하는 우선순위

스마트 목은 필드를 생성할 때 다음 우선순위로 동작합니다.

  1. 목 필드(Mock Field)
  2. 속성 이름 매칭(Property Name Matching)
  3. JSON Schema 타입 및 제약 조건

스마트 목 설정 화면

1. 목 필드

특정 필드에 사용자 지정 값 또는 표현식을 지정하면 가장 먼저 적용됩니다.

  • Fixed value: 항상 같은 값 반환
  • Faker statement: 규칙에 따라 동적 값 생성

예를 들어 currency를 항상 USD로 반환해야 한다면 고정 값을 사용합니다. status에는 여러 상태 중 하나를 반환하는 Faker 구문을 적용할 수 있습니다.

2. 속성 이름 매칭

목 필드가 없으면 Apidog는 속성 이름을 내장 규칙과 비교합니다.

예를 들어 다음 필드명은 의미 기반으로 적절한 값을 생성할 수 있습니다.

{
  "email": "user@example.com",
  "phone": "+1-415-555-0100",
  "createdAt": "2026-01-01T00:00:00Z"
}
Enter fullscreen mode Exit fullscreen mode

필드명 매칭 규칙은 Mock Settings에서 확인하고 사용자 지정할 수 있습니다.

3. JSON Schema

필드명이 어떤 규칙에도 일치하지 않으면 스키마 타입과 제약 조건을 기준으로 값을 생성합니다.

다음 제약은 생성 결과에 반영됩니다.

  • enum
  • minimum, maximum
  • 문자열 길이
  • pattern
  • minItems, maxItems
  • 필수 속성 여부

예를 들어 status에 enum을 설정하면 스마트 목은 지정하지 않은 상태값을 반환하지 않습니다. 배열에 minItems: 3을 설정하면 최소 3개 항목을 생성합니다.

스마트 목이 원하는 값을 만들지 못할 때

스마트 목은 추론 기반이므로 필드명이 모호하면 기대와 다른 값을 만들 수 있습니다.

예를 들어:

  • sku가 일반 문자열로 생성됨
  • total이 원하는 소수점 범위를 벗어남
  • currency가 항상 특정 값이어야 함
  • 내부 코드 형식이 정규식 규칙을 따라야 함

다음 순서로 조정하세요.

1. 스키마 제약 조건 강화

먼저 스키마로 표현할 수 있는 요구 사항인지 확인합니다.

{
  "type": "object",
  "properties": {
    "sku": {
      "type": "string",
      "pattern": "^SKU-[0-9]{6}$"
    },
    "total": {
      "type": "number",
      "minimum": 0.01,
      "maximum": 9999.99
    },
    "status": {
      "type": "string",
      "enum": ["pending", "shipped", "delivered"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

스키마 제약만으로 해결되면 별도 목 설정을 추가할 필요가 없습니다.

2. 목 필드 설정

스키마로 표현하기 어려운 요구 사항은 해당 속성의 목 필드로 설정합니다.

  • currency가 항상 USD여야 함 → Fixed value
  • 특정 형식의 동적 식별자가 필요함 → Faker statement
  • 개발 중 특정 상태를 강제로 재현해야 함 → Fixed value

Faker 표현식 사용법은 Apidog에서 Faker를 사용하는 방법을 참고하세요. Apidog의 Faker 레이어는 Mock.js와 같은 아이디어를 기반으로 합니다.

3. 속성 이름 매칭 규칙 추가

여러 엔드포인트에서 같은 필드명이 반복된다면 프로젝트 수준 규칙을 추가하는 편이 효율적입니다.

  1. Settings로 이동합니다.
  2. General Settings → Feature Settings → Mock Settings를 엽니다.
  3. New를 클릭합니다.
  4. 필드명 조건을 정의합니다.
  5. 해당 조건에 사용할 목 표현식을 지정합니다.

예를 들어 모든 sku 필드에 공통 규칙을 적용하면 각 엔드포인트마다 같은 설정을 반복하지 않아도 됩니다.

목 응답 우선순위

엔드포인트에 여러 응답 후보가 있을 때는 Project Settings의 Default mock method가 응답 선택 순서를 결정합니다.

스마트 목 우선

기본 설정입니다.

Mock Expectation → Smart Mock
Enter fullscreen mode Exit fullscreen mode

먼저 일치하는 목 기대(Mock Expectation)를 확인하고, 없으면 스마트 목이 응답을 생성합니다.

응답 예시 우선 

Mock Expectation → Response Example → Smart Mock
Enter fullscreen mode Exit fullscreen mode

먼저 목 기대를 확인하고, 그다음 응답 예시를 사용합니다. 예시가 없을 때 스마트 목이 대체 응답을 생성합니다.

중요한 규칙은 하나입니다.

조건이 일치하는 목 기대(Mock Expectation)는 항상 가장 높은 우선순위를 가집니다.

예를 들어 userId=9999일 때만 404를 반환하도록 목 기대를 설정했다면, 스마트 목 우선 여부나 응답 예시 존재 여부와 관계없이 해당 조건부 응답이 반환됩니다.

조건부 응답 설정은 Apidog에서 조건부 API 응답을 목업하는 방법에서 확인할 수 있습니다.

로컬 목, 클라우드 목, 러너 목 선택하기

응답을 생성하는 방식과 목 서버가 실행되는 위치는 별개입니다. Apidog는 세 가지 호스팅 방식을 제공합니다.

방식 실행 위치 적합한 상황
로컬 목 내 컴퓨터 개인 개발, 빠른 UI 구현
클라우드 목 Apidog 서버 팀 공유, 배포된 프리뷰
러너 목 팀 자체 인프라 내부 네트워크 또는 자체 호스팅 환경

로컬 목

로컬 목은 Apidog 클라이언트를 통해 실행됩니다.

  • 기본 주소: 127.0.0.1:4523
  • Apidog 클라이언트가 열려 있어야 함
  • Apidog 웹에서는 사용할 수 없음
  • 다른 장치에서 접근하려면 머신의 LAN IP가 필요할 수 있음

클라우드 목

클라우드 목은 Apidog 서버에서 호스팅됩니다.

  • 기본적으로 꺼져 있음
  • 환경 관리에서 활성화 필요
  • URL은 https://mock.apidog.com 사용
  • 팀원, QA, 배포 프리뷰에서 접근하기 적합
  • 프로덕션 트래픽이 아닌 테스트 용도로 사용

러너 목

러너 목은 팀 인프라에 자체 호스팅하는 방식입니다. 목 서버가 사내 네트워크나 자체 서버 안에 있어야 하는 환경에 적합합니다.

각 방식의 비교는 온라인 API 목업 도구 비교, 클라우드 설정은 Apidog 클라우드 목 가이드에서 확인할 수 있습니다.

라우팅 시 주의할 점

목 URL을 호출할 때 다음 규칙을 확인하세요.

경로는 /로 시작해야 함

다음과 같이 경로가 /로 시작해야 목 환경에서 올바르게 라우팅됩니다.

/orders
Enter fullscreen mode Exit fullscreen mode

선행 슬래시가 없는 경로 또는 완전한 URL은 의도한 목 환경을 거치지 않을 수 있습니다.

동일한 메서드와 경로가 중복될 때

같은 HTTP 메서드와 경로를 가진 API가 여러 개라면 경로 모드만으로 구분할 수 없습니다. 이 경우 쿼리 파라미터를 추가해 특정 엔드포인트를 지정합니다.

?apidogApiId={endpointId}
Enter fullscreen mode Exit fullscreen mode

새 요청은 새 데이터를 생성할 수 있음

동적 필드는 요청할 때마다 다시 생성될 수 있습니다. 같은 응답이 계속 보인다면 새 요청이 아니라 클라이언트 캐시나 기존 응답 보기를 확인하고 있는지 점검하세요.

Apidog CLI로 계약 검증 자동화

목 서버 자체는 Apidog GUI 및 클라우드 기능으로 동작합니다. Apidog CLI는 터미널에서 목 서버를 호스팅하거나 시작하는 도구가 아닙니다.

CLI의 역할은 프로젝트가 변경될 때 API 계약과 테스트를 자동화하는 것입니다.

스마트 목은 응답 스키마를 기반으로 생성되므로, 정확한 목업을 유지하려면 스키마도 최신 상태여야 합니다. Apidog CLI와 Cursor, Claude Code, Trae, Codex 같은 AI 코딩 에이전트를 함께 사용하면 엔드포인트와 스키마 업데이트를 개발 워크플로우에 연결할 수 있습니다.

백엔드가 준비된 뒤에는 동일한 API 계약을 기준으로 테스트 시나리오를 CI에서 실행할 수 있습니다.

apidog run -t <scenario_id> -e <env_id> -r html,cli
Enter fullscreen mode Exit fullscreen mode

CLI 설치 및 인증 예시:

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

Node.js v16 이상이 필요합니다. CI/CD 연결 방법은 CI/CD 파이프라인에서 Apidog 실행을 참고하세요.

자주 묻는 질문

스마트 목을 사용하려면 코드를 작성해야 하나요?

아니요. 응답 스키마가 있으면 스마트 목이 자동으로 데이터를 생성합니다. 특정 필드를 고정하거나 동적 생성 규칙을 세밀하게 제어할 때만 목 필드, Faker 구문 또는 목 스크립트를 사용합니다. 자세한 개념은 목 API 개요를 참고하세요.

목 URL이 응답을 반환하지 않는 이유는 무엇인가요?

다음을 확인하세요.

  1. 엔드포인트에 응답 정의와 스키마가 있는지
  2. 경로가 /로 시작하는지
  3. 로컬 목이라면 Apidog 클라이언트가 실행 중인지
  4. 올바른 프로젝트, 버전, 서버 번호를 사용하는지

스마트 목이 특정 값만 반환하게 하려면 어떻게 하나요?

속성의 목 필드(Mock Field)를 설정하세요.

  • 항상 같은 값 → Fixed value
  • 제한된 규칙 안에서 다양한 값 → Faker statement

목 필드는 속성명 매칭과 스키마 기본값보다 우선합니다.

팀원이 내 로컬 목에 접근할 수 있나요?

로컬 목은 127.0.0.1:4523에서 실행되며 Apidog 클라이언트가 열려 있는 동안에만 사용할 수 있습니다. 팀과 안정적으로 공유하려면 클라우드 목을 활성화하세요.

응답 예시와 스마트 목이 모두 있으면 무엇이 반환되나요?

Default mock method 설정에 따라 달라집니다.

  • Smart Mock First: 스마트 목이 생성한 응답 사용
  • Response example first: 응답 예시를 먼저 사용

단, 조건이 일치하는 목 기대(Mock Expectation)가 있으면 항상 그것이 우선합니다.

마무리

스마트 목은 응답 스키마를 바로 사용할 수 있는 목 API로 바꿉니다. 프런트엔드 작업을 시작하려면 다음만 수행하면 됩니다.

  1. 엔드포인트 응답 스키마를 정의합니다.
  2. API 또는 Mock 탭에서 목 URL을 복사합니다.
  3. curl, 프런트엔드 앱, 테스트 도구로 호출합니다.
  4. 결과를 조정해야 하면 스키마 제약, 목 필드, 속성명 매칭 규칙을 사용합니다.
  5. 조건부 응답이 필요하면 목 기대를 추가합니다.

Top comments (0)