Apidog에서 API 스펙으로 클라이언트 코드 생성하기

엔드포인트를 정의한 뒤 앱에서 호출하려면 URL, 헤더, 인증 토큰, 쿼리 문자열을 requests나 fetch 호출에 연결해야 합니다. 문자 하나라도 잘못 복사하면 서버가 왜 401을 반환하는지 오랫동안 추적하게 됩니다.

오늘 Apidog 사용해 보기

이 상용구 코드를 직접 작성할 필요는 없습니다. API를 Apidog에서 설계했다면 엔드포인트 사양을 읽어 현재 사용하는 언어에 붙여넣을 수 있는 요청 스니펫을 생성할 수 있습니다. 터미널 확인용 cURL, 스크립트용 Python requests, 프런트엔드용 JavaScript fetch 또는 Axios 등을 선택할 수 있습니다.

이 글에서는 다음을 다룹니다.

1. 실제 엔드포인트에서 요청 코드를 생성하는 방법
2. 실제 파라미터와 인증 값을 포함한 스니펫을 얻는 방법
3. 사양 변경 후 생성 코드가 오래되지 않게 유지하는 방법

더 넓은 선택지가 필요하다면 API 코드 생성 도구 개요도 참고할 수 있습니다.

이 방식은 사양을 단일 진실 공급원(single source of truth)으로 취급한다는 원칙에 기반합니다. 이는 OpenAPI Specification의 기본 원리와도 같습니다. 정의를 한 번 정확히 관리하면 요청 코드는 그 정의에서 파생됩니다.

클라이언트 코드 생성기는 실제로 무엇을 하는가

Apidog는 엔드포인트 정의를 언어별 요청 스니펫으로 변환합니다.

예를 들어 GET /orders를 정의하고 Python의 Requests를 선택하면, 사양에 선언된 URL, 헤더, 파라미터를 사용해 해당 경로를 호출하는 코드를 생성합니다.

다만 범위를 명확히 이해해야 합니다.

• 생성 결과: 단일 HTTP 요청을 위한 코드 스니펫
• 생성 대상: cURL, Python requests, JavaScript fetch, Axios 등의 호출 코드
• 생성하지 않는 대상: 모델, 페이지네이션 도우미, 버전 관리가 포함된 완전한 SDK 패키지

즉, 코드에 바로 삽입할 호출 하나가 필요할 때 적합합니다.

이 워크플로는 디자인 우선 API 개발과도 자연스럽게 연결됩니다. 계약을 먼저 정의하고 그 정의에서 요청 코드를 생성하면, 모든 소비자가 동일한 API 계약을 기준으로 작업할 수 있습니다.

생성기를 여는 두 가지 방법

Apidog에서는 같은 코드 생성 패널을 두 위치에서 열 수 있습니다.

방법 1: Documentation 탭에서 열기

엔드포인트 문서를 보고 있는 상태라면 다음 순서로 진행합니다.

1. API의 Documentation 탭을 엽니다.
2. 오른쪽의 Generate Client Code를 클릭합니다.
3. 언어와 라이브러리 변형을 선택합니다.
4. 생성된 코드를 복사합니다.

문서를 확인하면서 바로 호출 코드를 가져와야 할 때 가장 빠른 방법입니다.

방법 2: Run 탭에서 열기

요청을 테스트하는 중이라면 다음 순서가 더 자연스럽습니다.

1. API의 Run 탭을 엽니다.
2. 코드 아이콘 </>을 클릭합니다.
3. 언어와 변형을 선택합니다.
4. 스니펫을 복사합니다.

두 방법 모두 동일한 코드 생성 패널을 엽니다.

GET /orders용 Python 호출 생성하기

이제 주문 목록을 상태별로 필터링하고 페이지네이션하는 GET /orders 엔드포인트를 예로 들어 보겠습니다.

1단계: 엔드포인트를 열고 언어 선택

엔드포인트의 Documentation 탭에서 Generate Client Code를 클릭합니다.

Apidog는 다음과 같은 언어와 변형을 제공합니다.

• Shell: cURL, cURL-Windows, Httpie, wget, PowerShell
• JavaScript: Fetch, Axios, jQuery, XHR, Native, Request, Unirest
• Python: http.client, Requests
• Java: Unirest, OkHttp
• Go: Native
• PHP: cURL, Guzzle, pecl_http, HTTP_Request2
• Others: Swift(URLSession), C(libcurl), C#, Objective-C, Ruby, OCaml, Dart, R, Raw HTTP

이 예시에서는 Python과 Requests를 선택합니다.

import requests

url = "https://api.example.com/orders"

querystring = {"status": "shipped", "page": "1"}

headers = {"Accept": "application/json"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

생성된 코드는 사양에 정의된 경로, 헤더, 파라미터를 반영합니다. 복사한 뒤 프로젝트의 설정 값에 맞게 URL이나 환경 변수를 조정하면 됩니다.

2단계: 사양 기반 스니펫의 범위 이해하기

사양에서 직접 생성한 스니펫에는 API 사양 정보가 포함되지만, 실제 요청에 사용한 인증 토큰이나 런타임 파라미터 값까지 자동으로 포함되지는 않습니다.

예를 들어 보호된 엔드포인트라면 아래와 같은 실제 인증 헤더가 필요할 수 있습니다.

Authorization: Bearer <token>

사양 기반 코드는 호출의 구조와 정의된 예제 값을 제공하지만, 실제 서비스에 접근하는 비밀 토큰은 별도로 처리해야 합니다.

실제 파라미터와 인증 값을 포함한 코드 얻기

실제로 전송한 값과 인증 정보를 포함한 스니펫이 필요하다면 Actual Request 탭을 사용합니다.

3단계: 요청을 먼저 전송하기

다음 순서로 진행합니다.

1. Edit 탭에서 엔드포인트를 정의합니다.
2. Run 탭으로 이동합니다.
3. 쿼리 파라미터, 헤더, 인증 정보를 설정합니다.
4. Send를 클릭해 요청을 전송합니다.
5. 응답이 도착하면 Actual Request 탭으로 이동합니다.
6. 생성된 클라이언트 코드를 확인하고 복사합니다.

디자인 우선 방식에서는 사양에 정의한 요청 파라미터가 Run 탭에 자동으로 채워집니다. 요청 우선 방식에서는 Run 탭에서 값을 직접 입력할 수 있습니다.

실제 요청을 보낸 뒤 확인하는 스니펫은 다음과 같이 구체적인 값과 인증 헤더를 포함할 수 있습니다.

import requests

url = "https://api.example.com/orders"

querystring = {"status": "shipped", "page": "1"}

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer sk_live_51H8xY2..."
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

실제 토큰은 비밀 정보입니다. 위와 같은 값을 Git에 커밋하지 말고 환경 변수나 비밀 관리 도구로 분리하십시오. 이는 Stripe 문서가 라이브 키에 권장하는 방식과 같은 주의가 필요합니다.

예를 들어 Python에서는 다음처럼 처리할 수 있습니다.

import os
import requests

url = "https://api.example.com/orders"

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {os.environ['API_TOKEN']}",
}

params = {
    "status": "shipped",
    "page": "1",
}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()

print(response.json())

POST 및 PUT 요청 본문 처리

GET /orders에는 요청 본문이 없지만, POST /orders나 PUT /orders/{id} 코드를 생성하려면 요청 본문을 구성해야 합니다.

Apidog에서는 코드를 생성하기 전에 Run 탭에서 JSON 또는 XML 본문을 준비할 수 있습니다.

본문 데이터는 두 가지 방식으로 만들 수 있습니다.

1. 엔드포인트 사양에 정의된 예제 사용
2. 자동 생성(Auto-generate)으로 스키마에 맞는 본문 생성

자동 생성(Auto-generate) 드롭다운에는 다음 모드가 있습니다.

• 예제(Examples): 미리 정의된 요청 본문 예제를 선택
• 매번 생성(Generate Each Time): 스마트 모의(mock) 규칙으로 매번 새로운 스키마 유효 데이터를 생성

생성 방식은 다음 하위 옵션으로 조절할 수 있습니다.

• 예제 값 먼저 사용(Use Example Values First)
• 기본 값 먼저 사용(Use Default Values First)
• 모의 값 사용(Use Mock Value)
• 필드 이름만 생성(Generate Field Names Only)
• 요청 예제 사용(Use Request Example)

사양에 신뢰할 수 있는 예제가 있다면 예제 값 먼저 사용이 적합합니다. 모든 필드에 대해 현실적인 임시 데이터가 필요하다면 모의 값 사용을 선택합니다.

요청 본문의 자동 생성(Auto-generate) 기능은 Apidog 2.7.0 이상이 필요합니다. 옵션이 보이지 않으면 앱 버전을 확인하십시오.

OpenAPI로부터 API 문서를 자동 생성할 때 스키마와 예제를 잘 정의해 두면, 이후 요청 본문을 생성할 때 수동 편집을 줄일 수 있습니다.

타임스탬프나 임의 주문 ID처럼 요청마다 바뀌는 값이 필요하다면 하드코딩하지 마십시오.

1. 파라미터 입력 상자 옆의 매직 지팡이(magic wand) 아이콘을 클릭합니다.
2. 또는 JSON/XML 본문의 동적 값 삽입(Insert Dynamic Value) 버튼을 사용합니다.
3. 본문을 준비한 뒤 Send를 클릭합니다.
4. Actual Request 탭에서 실제 요청 기반 스니펫을 복사합니다.

요청 스니펫과 애플리케이션 코드 중 무엇을 선택할까

선택 기준은 간단합니다. 이 호출을 몇 번, 어디에서 사용할지 판단하면 됩니다.

단일 요청 스니펫이 적합한 경우

다음 작업에는 cURL, fetch, 단순한 requests.get 같은 단일 스니펫이 적합합니다.

• 403 또는 401 오류 디버깅
• 이슈나 티켓에 재현 가능한 요청 공유
• 터미널에서 빠르게 API 확인
• 내부 문서에 요청 예제 추가
• 특정 헤더나 파라미터 조합 테스트

스니펫은 자체 완결적이므로 주변 코드 구조가 필요 없습니다.

구조화된 애플리케이션 코드가 적합한 경우

서비스 모듈에서 여러 번 호출하는 엔드포인트라면 생성한 스니펫을 함수로 감싸고, 오류 처리와 설정 분리를 추가하는 편이 좋습니다.

예를 들어 GET /orders를 여러 위치에서 호출한다면 다음처럼 구성할 수 있습니다.

import os
import requests

BASE_URL = os.environ["API_BASE_URL"]
API_TOKEN = os.environ["API_TOKEN"]


def get_orders(status: str, page: int = 1) -> dict:
    response = requests.get(
        f"{BASE_URL}/orders",
        headers={
            "Accept": "application/json",
            "Authorization": f"Bearer {API_TOKEN}",
        },
        params={
            "status": status,
            "page": str(page),
        },
        timeout=10,
    )
    response.raise_for_status()
    return response.json()

같은 인증 정보와 공통 헤더를 여러 엔드포인트에서 사용한다면 중앙 집중화하는 편이 낫습니다. Apidog에서 전역 파라미터 설정 가이드에서는 각 스니펫에 토큰을 반복하지 않고 헤더와 변수를 한 번 정의하는 방법을 확인할 수 있습니다.

사양 우선 습관으로 생성 코드 정확성 유지하기

생성된 코드는 기반 사양만큼만 정확합니다.

예를 들어 GET /orders에 region 쿼리 파라미터를 추가한 뒤 기존 스니펫을 다시 생성하지 않으면, 복사해 둔 코드는 새 계약을 반영하지 않습니다.

이를 방지하려면 다음 원칙을 따르십시오.

1. API 사양을 유지 관리 대상의 기준으로 둡니다.
2. 스니펫은 필요할 때마다 사양에서 다시 생성합니다.
3. 사양 변경 후 저장된 테스트를 실행합니다.
4. 실제 애플리케이션 코드에서는 인증 정보와 환경별 URL을 분리합니다.

사양 우선 모드를 사용하면 정의를 권위 있는 계약으로 유지하고, 생성되는 요청 코드가 최신 API 계약을 반영하도록 관리할 수 있습니다.

JavaScript 스니펫을 조정해야 한다면 MDN Fetch API 문서를 참고하는 것이 좋습니다.

Apidog CLI로 워크플로 자동화하기

클라이언트 코드 생성은 GUI에서 수행합니다. 패널에서 스니펫을 복사하며, 클라이언트 코드를 출력하는 별도 CLI 명령은 없습니다.

하지만 Apidog CLI는 생성 코드의 기반이 되는 두 가지를 유지하는 데 유용합니다.

• 최신 API 사양
• 엔드포인트가 실제로 동작한다는 테스트 결과

Node.js v16+ 환경에서 CLI를 설치합니다.

npm install -g apidog-cli

이후 액세스 토큰으로 인증합니다.

apidog login --with-token <YOUR_ACCESS_TOKEN>

저장된 테스트 시나리오를 실행하려면 다음 명령을 사용합니다.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

옵션 의미는 다음과 같습니다.

• -t: 테스트 시나리오 ID
• -e: 환경 ID
• -r: 리포터 형식 (cli, html, junit)

Apidog CLI GitHub Actions 가이드처럼 이 명령을 CI 파이프라인에 연결하면, 모든 푸시에서 GET /orders가 사양대로 동작하는지 확인할 수 있습니다.

CLI가 클라이언트 코드를 직접 생성하지는 않지만, 생성 코드가 의존하는 API 계약을 보호하는 역할을 합니다.

자주 묻는 질문

생성된 코드에 API 키와 토큰이 포함되나요?

기본적으로 사양에서 생성한 코드는 실제 파라미터 값이나 인증 토큰을 포함하지 않습니다.

실제 값과 토큰이 포함된 스니펫이 필요하다면 요청을 먼저 전송한 뒤 Actual Request 탭에서 코드를 확인하십시오. 이 스니펫에 포함된 토큰은 비밀 정보로 취급해야 합니다.

Apidog는 어떤 언어와 라이브러리용 코드를 생성하나요?

Shell(cURL, Httpie, wget, PowerShell), JavaScript(Fetch, Axios, jQuery, XHR 등), Python(http.client, Requests), Java(Unirest, OkHttp), Go, PHP, Swift, C, C#, Ruby, Dart, R 등 다양한 언어와 변형을 지원합니다.

생성기 패널에서 언어와 라이브러리 변형을 선택할 수 있습니다.

요청 본문 자동 생성 옵션이 보이지 않는 이유는 무엇인가요?

요청 본문의 자동 생성(Auto-generate) 기능은 Apidog 2.7.0 이상이 필요합니다.

앱을 업데이트하면 JSON 또는 XML 본문을 생성할 때 Run 탭에서 해당 옵션을 사용할 수 있습니다. 사용 가능해지면 예제(Examples), 매번 생성(Generate Each Time) 및 생성 우선순위 옵션을 선택할 수 있습니다.

클라이언트 코드 생성은 유료 기능인가요?

Apidog 문서는 클라이언트 코드 생성에 대해 유료/무료 또는 클라우드/온프레미스 구분을 명시하지 않습니다. 문서에서 언급한 버전 요구 사항은 요청 본문 자동 생성(Auto-generate) 기능의 2.7.0 이상 요구 사항입니다.

Apidog 다운로드 후 생성기를 직접 확인할 수 있습니다.

생성한 호출이 실제로 작동하는지 어떻게 검증하나요?

스니펫을 생성한 뒤 저장된 테스트 시나리오로 엔드포인트를 검증하십시오.

Apidog로 테스트 시나리오 작성 가이드로 시나리오를 구성하고, CLI를 CI에서 실행하면 클라이언트를 다시 생성하기 전에 깨진 계약을 감지할 수 있습니다.

마무리

Apidog의 클라이언트 코드 생성 기능은 엔드포인트 사양을 현재 사용하는 언어에 붙여넣을 수 있는 요청 코드로 변환합니다.

실무에서는 다음 흐름을 따르면 됩니다.

1. 사양에서 기본 스니펫을 생성합니다.
2. 인증과 실제 파라미터가 필요하면 요청을 전송합니다.
3. Actual Request 탭에서 실제 값이 반영된 코드를 복사합니다.
4. 토큰과 환경별 설정은 코드에서 분리합니다.
5. 사양이 변경되면 스니펫을 다시 생성하고 테스트를 실행합니다.

Apidog를 다운로드한 뒤 GET /orders 엔드포인트를 정의하고, 몇 번의 클릭으로 동작하는 클라이언트 호출을 생성해 보십시오.