Apidog는 다양한 형식의 API 사양 가져오기를 지원하는 API 협업 및 관리 플랫폼입니다. OpenAPI/Swagger, Postman Collections, HAR 파일, cURL 명령어를 포함하여 거의 모든 주류 API 사양 형식을 직접 가져올 수 있습니다.
하지만 많은 실제 프로젝트에서 주요 과제는 API 사양을 가져오는 방법이 아니라, 애초에 가져올 수 있는 API 사양이 없다는 것입니다. 일부 오래된 시스템이나 레거시 시스템은 API 문서를 관리하지 않아 OpenAPI 또는 Swagger 파일이 없는 경우가 있습니다.
이러한 경우, 누락된 API 문서를 빠르게 재구성하거나 테스터가 실제 데이터로 작업할 수 있도록 테스트 케이스를 생성해야 한다면, 패킷 캡처 도구를 사용하는 것이 가장 빠른 접근 방식이 될 수 있습니다.
애플리케이션의 HTTP/HTTPS 트래픽을 캡처하고, 유용한 요청을 필터링하고, 이를 HAR 또는 cURL로 내보낸 다음 Apidog으로 가져오면, API 문서를 빠르게 생성하고 추가 API 테스트를 위한 기반을 마련할 수 있습니다.
트래픽 기록을 위한 다양한 도구들이 있습니다. 이 글에서는 Charles Proxy를 예시로 사용하여 관련된 특정 작업을 시연하지만, Proxyman, Fiddler 또는 브라우저에 내장된 개발자 도구와 같은 대안을 사용하여 패킷 캡처를 할 수도 있습니다. 핵심 워크플로는 이러한 도구들 전반에 걸쳐 본질적으로 동일합니다.
Charles 설치 및 기본 설정
Charles는 30일 무료 체험판을 제공합니다. 공식 웹사이트에서 최신 버전을 다운로드하여 시스템에 설치할 수 있습니다.
Charles를 처음 실행할 때, 네트워크 설정을 자동으로 구성할지 묻는 메시지가 나타날 수 있습니다. 필요한 권한을 부여하려면 "권한 부여(Grant Privileges)"를 선택하는 것이 좋습니다. 이를 통해 Charles는 시스템에서 HTTP 트래픽을 자동으로 캡처할 수 있습니다.
HTTPS 캡처를 위한 Charles 루트 인증서 설치
HTTPS 트래픽을 캡처하려면 Charles의 루트 인증서를 설치해야 합니다. 대부분의 최신 API는 HTTPS를 사용하므로 이 단계는 필수적입니다.
macOS에서:
- 메뉴 바에서 "Help → SSL Proxying → Install Charles Root Certificate"를 클릭합니다.
- 키체인 접근(Keychain Access) 애플리케이션이 자동으로 열립니다.
- Charles Proxy 인증서를 검색하여 찾습니다.
- 더블 클릭하여 신뢰 설정을 "항상 신뢰(Always Trust)"로 변경합니다.
Windows에서:
- 메뉴 바에서 "Help → SSL Proxying → Install Charles Root Certificate"를 클릭합니다.
- 설치 과정에서 "신뢰할 수 있는 루트 인증 기관(Trusted Root Certification Authorities)" 저장소에 인증서를 설치합니다.
SSL 프록싱 활성화
인증서가 설치되면 SSL 프록싱을 활성화해야 합니다:
- Charles 메뉴 바에서 Proxy → SSL Proxying Settings를 선택합니다.
- "Enable SSL Proxying" 옵션을 선택합니다.
3. 캡처하려는 도메인 이름(호스트)과 포트(포트 443)를 목록에 추가합니다.
4. 모든 도메인을 모니터링하려면 *를 사용할 수도 있습니다.
설정이 완료되면 Charles는 전체 HTTP/HTTPS 요청 및 응답을 캡처할 수 있습니다.
팁: 애플리케이션이 어떤 도메인을 사용하는지 확실하지 않다면, 먼저 애플리케이션을 자유롭게 작동시킨 다음 Charles 세션 목록의 "Encrypted" 아래에서 요청을 관찰할 수 있습니다. 해당 도메인을 확인한 다음 Charles의 SSL 프록싱 설정에 추가하세요.
애플리케이션에서 API 트래픽 기록
분석하려는 애플리케이션이나 웹페이지를 실행하고, 로그인, 데이터 쿼리, 양식 제출, 파일 업로드 등 다양한 기능과 상호 작용합니다. Charles 왼쪽의 세션 트리는 도메인과 URL별로 요청을 그룹화하여 실시간으로 업데이트됩니다.
특정 요청을 선택하면 오른쪽 패널에 해당 요청의 기본 정보와 응답 내용이 표시됩니다. "Contents" 탭에서는 JSON 및 기타 응답이 트리 구조로 축소되어 데이터 구조와 필드를 빠르게 이해하기 쉽습니다.
API 엔드포인트 필터링 및 내보내기
기록이 완료되면 많은 수의 요청이 캡처되었을 수 있습니다. 실제 API 호출 외에도 다양한 정적 리소스 요청, 타사 서비스 호출 및 기타 네트워크 트래픽이 있습니다. 이 시점에서 관심 있는 엔드포인트만 필터링하여 유지해야 합니다.
필터링 옵션
1. 특정 도메인 또는 경로에 집중:
도메인 또는 경로에서 마우스 오른쪽 버튼을 클릭하고 "Focus"를 선택합니다.
Charles는 해당 노드 아래의 요청만 유지하여 분석에 편리합니다.
2. 관련 없는 요청 제거:
관련 없는 요청에서 마우스 오른쪽 버튼을 클릭하고 "Clear"를 선택하여 제거합니다.
또는 여러 요청을 선택하고 일괄 삭제합니다.
3. 캐싱 문제 처리:
캐싱으로 인해 HTML 또는 JSON이 올바르게 표시되지 않으면, 마우스 오른쪽 버튼을 클릭하고 "No Caching"을 선택합니다.
이는 Charles가 이후 요청에서 캐싱을 무시하도록 하여 완전한 응답 내용을 캡처할 수 있도록 합니다.
HAR 파일로 내보내기
필터링이 완료되면 선택한 세션을 내보냅니다:
- 내보낼 세션을 선택합니다:
전체 도메인 노드를 선택하거나,
Cmd (Mac) 또는 Ctrl (Windows)를 누른 채 개별 요청을 선택할 수 있습니다.
메뉴 바에서 File → Export Session을 선택합니다.
내보내기 대화 상자에서 "HTTP Archive (.har)" 형식으로 내보내기를 선택하여 HAR 파일을 생성합니다.
Apidog으로 가져와 API 문서 자동 생성하기
이제 캡처된 트래픽을 Apidog으로 가져올 차례입니다:
- Apidog 클라이언트를 엽니다.
2. Project Settings → Import Data → .har File로 이동합니다.
3. Charles에서 내보낸 HAR 파일을 선택합니다.
Apidog은 파일 내용을 자동으로 파싱하고 감지된 엔드포인트 정보를 미리보기 영역에 표시합니다. 포함되는 내용은 다음과 같습니다:
- 감지된 엔드포인트 수
- 요청 메서드 (GET, POST, PUT, DELETE 등)
가져오기 프로세스 중에 다음과 같은 옵션을 구성할 수 있습니다:
- 가져올 모듈
- 기존 엔드포인트 덮어쓰기 여부
가져오기가 완료되면 해당 모듈에서 엔드포인트를 확인할 수 있습니다.
API 문서 다듬기 및 최적화
자동 생성된 API 문서는 훌륭한 시작점이지만, 비즈니스 요구 사항을 충족하기 위해서는 일반적으로 추가적인 조정이 필요합니다. 몇 가지 일반적인 개선 사항은 다음과 같습니다:
- 엔드포인트 이름 개선: 일반적인 이름을 더 설명적인 이름으로 변경합니다.
- 매개변수 설명 추가: 각 매개변수가 무엇을 하는지, 언제 사용해야 하는지를 문서화합니다.
- 응답 구성 요소 다듬기: 비즈니스 로직에 맞게 응답 구성 요소를 정리합니다.
- 예시 추가: 샘플 요청 및 응답을 포함합니다.
- 인증 구성: 엔드포인트에 인증이 필요한 경우, Apidog의 환경 변수 또는 인증 설정에서 해당 정보를 구성합니다. 이렇게 하면 테스트 시 API 호출이 올바르게 작동하도록 보장합니다.
마지막으로
패킷 캡처 도구를 사용하여 HTTP/HTTPS 트래픽을 기록하고 Apidog으로 가져오면 API 문서를 빠르게 생성하고 테스트를 위한 실제 데이터 지원을 제공할 수 있습니다.
브라우저, 데스크톱 클라이언트 또는 모바일 애플리케이션이든 상관없이 이 방법은 API 문서 준비에 소요되는 시간을 크게 줄이고 팀이 API 테스트 및 개발을 빠르게 시작할 수 있도록 합니다.