엔드포인트를 정의했고 앱에서 호출하려고 합니다. 이때 사양을 작동하는 코드로 변환하는 지루한 과정이 필요합니다. 올바른 URL, 헤더, 인증 토큰, 쿼리 문자열 등을 모두 requests 호출이나 fetch에 연결해야 합니다. 문자 하나라도 잘못 복사하면 서버가 왜 401을 반환하는지 20분 동안 고민하게 될 것입니다.
이러한 상용구 코드를 직접 작성할 필요는 없습니다. API가 Apidog에서 설계되었다면, Apidog 플랫폼은 엔드포인트 사양을 읽어 작업하는 언어로 바로 붙여넣을 수 있는 요청 스니펫을 제공합니다. 터미널에서 빠르게 확인하기 위한 cURL, 스크립트용 Python requests, 프런트엔드용 JavaScript fetch 또는 Axios 등이 있습니다. 이 가이드는 실제 엔드포인트에서 코드를 생성하는 방법, 실제 값을 포함하는 스니펫을 얻기 위해 요청을 먼저 보내야 할 때, 그리고 사양 변경 시 생성된 코드를 정확하게 유지하는 방법을 안내합니다. 더 넓은 선택지를 원하시면, API 코드 생성 도구에 대한 저희의 개요 글을 참조하시고, 여기서는 내장된 생성기를 직접 다뤄보겠습니다.
이 아이디어는 사양이 단일 진실 공급원(single source of truth)이라는 원칙에 기반하며, 이는 OpenAPI Specification의 기본 원리와 동일합니다. 정의를 한 번 정확하게 하면, 요청 코드는 그에 따라 생성됩니다.
클라이언트 코드 생성기는 실제로 무엇을 하는가
Apidog는 엔드포인트 정의를 언어 변형별 요청 스니펫으로 변환합니다. GET /orders를 지정하고 Python과 Requests 라이브러리를 선택하면, 사양에 선언된 헤더와 파라미터로 해당 경로를 호출하는 코드를 작성해줍니다. 이것은 요청 생성기로서, 선택한 언어와 HTTP 라이브러리 구문으로 단일 호출 코드를 생성합니다.
한 가지 중요한 점에 대해 정확한 기대치를 설정해야 합니다. 이 기능은 엔드포인트에 대한 요청 또는 클라이언트 코드를 생성하지만, 완전한 SDK나 버전이 있는 클라이언트 라이브러리 패키지를 생성하는 것은 아닙니다. 코드에 삽입할 curl 한 줄, Python requests 블록, 또는 JS fetch 스니펫이 필요하다면, 그것이 바로 얻게 될 결과입니다. 문서에서는 전체 라이브러리 생성기를 설명하지 않으므로, 모델과 페이지네이션 도우미가 내장된 다운로드 가능한 타입 지정 SDK를 기대하지 마십시오.
이것은 디자인 우선 API 개발 워크플로와 자연스럽게 연결됩니다. 계약을 정의하고 그로부터 직접 요청 코드를 생성하면, 모든 소비자는 Slack에 붙여넣은 스크린샷 대신 동일한 정확한 정의로부터 시작합니다.
생성기를 여는 두 가지 방법
Apidog는 동일한 기능에 접근할 수 있는 두 가지 진입점을 제공합니다. 현재 작업 중인 상황에 맞는 것을 사용하십시오.
첫 번째는 문서에서 접근하는 방법입니다. API의 Documentation 탭을 열고, 오른쪽의 Generate Client Code 버튼을 클릭하십시오. 이는 엔드포인트 문서를 읽고 해당 호출 코드를 원할 때 가장 빠른 경로입니다.
두 번째는 러너에서 접근하는 방법입니다. API의 Run 탭에서 코드 아이콘 </>을 클릭하십시오. 이 아이콘은 요청을 구성하고 보내는 곳 옆에 위치하므로, 이미 호출을 테스트하고 있을 때 자연스러운 선택입니다.
둘 다 동일한 패널을 엽니다. 거기서 언어와 변형을 선택하면 Apidog가 스니펫을 작성합니다.
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, plus a raw HTTP option
이 예시에서는 Python과 Requests 변형을 선택합니다. Apidog는 사양으로부터 다음과 같은 코드를 생성합니다.
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())
이것을 복사하여 스크립트에 붙여넣으면 작동하는 호출이 됩니다. 이것이 바로 디자인 우선 방식입니다. 스니펫은 엔드포인트가 선언하는 내용을 정확히 반영합니다.
2단계: 사양 전용 스니펫에 무엇이 포함되는지 이해하기
붙여넣기 전에 이해해야 할 함정이 있습니다. API 사양에서 직접 생성된 코드는 API 사양만 포함하며, 실제 요청 파라미터 값이나 인증 토큰은 포함하지 않습니다. 호출의 형태와 사양에 정의된 예제 값은 얻을 수 있지만, 보호된 엔드포인트에 실제로 도달하는 데 필요한 실제 Authorization: Bearer ... 헤더는 포함되지 않습니다.
이는 인증이 없는 호출이거나 토큰을 직접 채워 넣을 경우에는 문제가 없습니다. 보호된 GET /orders의 경우, 코드에 실제 값이 포함되기를 원할 것입니다.
3단계: 실제 값을 캡처하기 위해 요청을 먼저 보내기
실제 파라미터 값과 인증 정보를 포함하는 스니펫을 얻으려면, 먼저 요청을 보낸 다음 Actual Request 탭에서 코드를 확인하십시오.
디자인 우선 방식으로 작업하는 경우, 이것은 쉽습니다. Edit 탭에서 엔드포인트를 정의하고 Run 탭을 클릭하면 요청 파라미터가 사양으로부터 자동으로 채워집니다. 수동으로 설정하려면(요청 우선 모드), 대신 Run 탭에서 요청 파라미터를 수동으로 입력하십시오. 어느 쪽이든 인증 토큰을 추가한 다음 Send를 클릭하여 요청을 전송합니다.
응답이 돌아오면 Actual Request 탭으로 전환하고 스크롤하여 클라이언트 코드를 찾으십시오. 이제 생성된 스니펫에는 실제로 전송된 구체적인 값과 인증 헤더가 포함됩니다.
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())
이것이 두 가지 경로의 차이점입니다. 디자인 우선 모드는 사양에서 파라미터를 자동으로 채워 넣고, 요청 우선 모드는 직접 입력할 수 있게 합니다. 둘 다 Send를 누르면 동일한 Actual Request 스니펫을 제공합니다. 위에 있는 실제 토큰과 같은 것은 비밀로 취급하고 git에 커밋하는 어떤 것에도 포함하지 마십시오. Stripe 문서에서 라이브 키에 대해 권장하는 것과 동일한 주의가 여기에 적용됩니다.
POST 및 PUT 요청 본문 처리
GET /orders는 본문이 없지만, POST /orders 또는 PUT /orders/{id}에 대한 코드를 생성하는 순간 스니펫에 요청 본문이 필요합니다. Apidog는 코드를 생성하기 전에 Run 탭에서 본문을 구성하는 데 도움을 줍니다.
JSON 또는 XML 본문에는 두 가지 소스가 있습니다. 엔드포인트 사양의 미리 정의된 예제를 사용하거나, 자동 생성(Auto-generate)을 클릭하여 스키마와 일치하는 본문 구조를 만들 수 있습니다. 자동 생성(Auto-generate) 드롭다운은 두 가지 모드를 제공합니다.
- 예제(Examples): 미리 정의된 요청 본문 예제를 수동으로 선택합니다.
- 매번 생성(Generate Each Time): 스마트 모의(mock) 규칙에 따라 매번 데이터를 재생성하여 항상 신선하고 스키마에 유효한 값을 얻을 수 있습니다.
자동 생성 선호도(Auto-generation Preference) 하위 옵션인 예제 값 먼저 사용(Use Example Values First), 기본 값 먼저 사용(Use Default Values First), 모의 값 사용(Use Mock Value), 필드 이름만 생성(Generate Field Names Only), 요청 예제 사용(Use Request Example)을 통해 데이터가 생성되는 방식을 조절할 수 있습니다. 사양에 좋은 예제가 있고 이를 따르기를 원할 때는 예제 값 먼저 사용(Use Example Values First)을 선택하십시오. 모든 필드에 대해 현실적인 생성 데이터가 필요할 때는 모의 값 사용(Use Mock Value)을 선택하십시오.
버전 참고: 요청 본문에 대한 자동 생성(Auto-generate) 옵션은 Apidog 2.7.0 이상 버전이 필요합니다. 해당 옵션이 보이지 않으면 앱을 업데이트하십시오. OpenAPI로부터 API 문서를 자동 생성하여 얻는 것과 같은 예제를 포함한 잘 정의된 스키마는 이 단계를 통해 수동 편집이 거의 필요 없는 깔끔한 본문을 생성할 수 있게 합니다.
새로운 타임스탬프나 임의의 주문 ID처럼 요청마다 변경되는 값이 필요한 경우, 값을 하드코딩하는 대신 동적 값을 삽입하십시오. 파라미터 입력 상자 옆에 있는 매직 지팡이(magic wand) 아이콘을 클릭하거나, JSON 또는 XML 요청 본문 내의 동적 값 삽입(Insert Dynamic Value) 버튼을 사용하십시오. 본문이 준비되면 Send를 클릭한 다음, 이전과 마찬가지로 Actual Request 탭에서 완성된 스니펫을 확인하십시오.
요청 스니펫과 비즈니스 모델 호출 중 언제 사용할 것인가
간단한 판단 기준: 얼마나 많은 코드를 복사해야 할까요?
일회성 작업을 수행할 때는 단일 요청 스니펫(cURL, fetch, 단순한 requests.get)을 사용하십시오. 엔드포인트가 왜 403을 반환하는지 디버깅하거나, 티켓에 재현 가능한 호출을 공유하거나, 터미널에서 빠르게 확인하거나, 자신의 문서에 예제를 붙여넣을 때 유용합니다. 이것은 자체적으로 완결되며 주변 구조가 필요 없습니다.
실제 애플리케이션 로직 내에서 호출이 사용될 때는 더 완전한 비즈니스 모델 스타일 코드(헤더, 파라미터 및 응답 처리가 명시된 Axios 또는 requests 블록)를 선호하십시오. GET /orders가 세 곳에서 호출되는 서비스 모듈 안에 들어간다면, 함수로 묶고 오류 처리를 추가하며 재사용할 수 있는 구조화된 버전을 원할 것입니다. 생성기는 선택한 변형에 따라 두 가지 형태를 제공하므로, 코드가 사용될 위치에 맞춰 형태를 선택하십시오.
전체 프로젝트에서 동일한 인증으로 동일한 엔드포인트를 호출하는 경우, 공유 부분을 중앙 집중화하는 것이 더 깔끔합니다. Apidog에서 전역 파라미터 설정에 대한 저희 가이드는 각 스니펫에서 토큰을 반복하는 대신 모든 생성된 호출이 이를 상속하도록 헤더와 변수를 한 번 정의하는 방법을 보여줍니다.
사양 우선 습관으로 생성된 코드의 정확성 유지
생성된 코드는 그 뒤에 있는 사양만큼만 정확합니다. GET /orders에 region 쿼리 파라미터를 추가하고 재생성하는 것을 잊으면, 복사된 스니펫은 소리 없이 틀리게 됩니다. 해결책은 사양을 유지 관리해야 할 대상으로, 코드를 필요에 따라 재생성하는 파생된 결과물로 취급하는 것입니다. Apidog의 사양 우선 모드는 정의를 권위 있는 것으로 유지하여, 생성하는 요청 코드가 오래된 것이 아닌 항상 최신 계약을 반영하도록 합니다.
스니펫 자체의 구문에 대해서는, Apidog가 생성하는 JavaScript 변형을 이해하거나 조정하고 싶을 때 Fetch API에 대한 MDN 문서가 훌륭한 참고 자료가 됩니다.
Apidog CLI로 워크플로 자동화
코드 생성 자체는 GUI 작업입니다. 패널에서 스니펫을 복사하며, 클라이언트 코드를 출력하는 별도의 CLI 명령은 없습니다. Apidog CLI가 잘하는 것은 코드 생성이 의존하는 두 가지, 즉 최신 사양과 생성된 클라이언트가 실제로 작동함을 증명하는 통과하는 테스트를 유지하는 것입니다.
npm install -g apidog-cli (Node.js v16+)로 설치하고 인증하십시오.
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 가이드에 설명된 대로 이를 파이프라인에 연결하면, 모든 푸시가 GET /orders가 사양에서 약속한 대로 여전히 작동하는지 확인합니다. 이는 누군가가 클라이언트를 재생성하기 전에 이루어집니다. CLI는 클라이언트 코드를 작성하지는 않지만, 그 코드가 기반하는 계약을 보호합니다.
자주 묻는 질문(FAQ)
생성된 코드에 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 및 기타 언어를 지원합니다. 생성기 패널에서 언어와 특정 변형을 선택할 수 있습니다.
요청 본문에 대한 자동 생성 옵션이 보이지 않는 이유는 무엇인가요?
해당 옵션은 Apidog 2.7.0 이상 버전이 필요합니다. 앱을 업데이트하면 JSON 또는 XML 본문을 생성할 때 Run 탭에 나타날 것입니다. 사용 가능해지면 자동 생성(Auto-generate) 드롭다운은 예제(Examples)와 매번 생성(Generate Each Time)을 제공하며, 값 생성 방식에 대한 선호도 하위 옵션도 함께 제공됩니다.
클라이언트 코드 생성은 유료 기능인가요?
Apidog 문서는 클라이언트 코드 생성에 대해 유료/무료 또는 클라우드/온프레미스 구분을 명시하지 않습니다. 유일하게 언급된 버전 요구 사항은 자동 생성(Auto-generate) 요청 본문 옵션에 2.7.0 이상 버전이 필요하다는 것입니다. 유료 플랜 없이도 Apidog를 다운로드하여 생성기를 사용해 볼 수 있습니다.
생성된 호출이 실제로 작동하는지 어떻게 확인할 수 있나요?
스니펫을 생성한 다음, 저장된 테스트로 엔드포인트를 검증하십시오. Apidog로 테스트 시나리오 작성에 대한 저희 가이드는 시나리오를 구성하는 방법을 보여주며, CLI는 이를 CI에서 실행하여 클라이언트를 재생성하기 전에 깨진 계약으로 인해 빌드가 실패하도록 할 수 있습니다.
마무리
Apidog에서 클라이언트 코드를 생성하면 엔드포인트 사양이 작업하는 어떤 언어로든 바로 붙여넣을 수 있는 요청으로 바뀝니다. 그리고 Actual Request 탭은 빈 템플릿 대신 실제 값과 인증 정보를 스니펫에 넣는 비결입니다. 사양을 권위 있는 것으로 유지하고, 변경될 때마다 재생성하며, 저장된 테스트가 호출이 여전히 작동하는지 확인하게 하십시오. Apidog를 다운로드하여 이 가이드를 따라 GET /orders 엔드포인트를 정의하고 몇 번의 클릭으로 작동하는 클라이언트 호출을 복사하십시오.