Proxyman vs mitmproxy: 캡처한 트래픽에서 OpenAPI 생성하기
API는 있지만 문서가 없거나 오래되었을 수 있습니다. 앱에서 요청은 볼 수 있어도, 모든 경로, 파라미터, 응답을 직접 작성하려면 몇 시간이 걸릴 것입니다.
HTTP 디버깅 도구가 도움이 될 수 있습니다. 앱이 보내는 실제 요청을 캡처할 수 있기 때문입니다. 다음 단계는 그 요청을 사람과 도구가 이해할 수 있는 OpenAPI 문서로 바꾸는 것입니다.
mitmproxy와 Proxyman 모두 이 워크플로에 활용할 수 있습니다. 가장 큰 차이는 필요한 단계의 수입니다. mitmproxy에서는 일반적으로 별도의 명령줄 도구를 사용합니다. Proxyman에서는 OpenAPI 내보내기가 앱에 기본으로 포함되어 있습니다.
이 가이드에서 다음 내용을 배웁니다:
- OpenAPI가 무엇이며 왜 유용한지
- 현재 mitmproxy 워크플로가 어떻게 동작하는지
- 그 워크플로가 초보자에게 어려울 수 있는 부분
- Proxyman으로 OpenAPI YAML 또는 HTML을 내보내는 방법
- 생성된 문서를 공유하기 전에 확인할 사항
OpenAPI란 무엇인가요?
OpenAPI는 REST API를 설명하기 위한 표준 형식입니다. 이 형식으로 사람과 소프트웨어에 다음과 같은 내용을 알려 줍니다:
- 사용 가능한 URL
GET,POST,DELETE같이 사용하는 HTTP 메서드- 받는 쿼리 파라미터 또는 경로 파라미터
- 요청 본문의 구조
- 서버가 반환할 수 있는 값
- 사용되는 상태 코드
예를 들어 앱이 다음과 같은 요청을 보낼 수 있습니다:
GET https://api.example.com/users/123
OpenAPI 문서는 이 요청을 /users/{id}와 같은 경로로 설명할 수 있습니다. 서버가 반환하는 JSON도 설명할 수 있습니다.
OpenAPI 파일은 보통 YAML 또는 JSON으로 작성합니다. Swagger Editor 같은 도구로 열어 보거나, API 문서를 만드는 데 사용하거나, 이 파일로부터 클라이언트 코드를 생성할 수 있습니다.
실제 트래픽에서 OpenAPI를 생성하는 이유는 무엇인가요?
가장 좋은 API 문서는 API 소스 코드와 함께 작성되고 관리됩니다. 하지만 실제 프로젝트에서는 문서가 불완전하거나, 오래되었거나, 아예 없을 수도 있습니다.
캡처한 트래픽으로 초안을 먼저 만들면 다음과 같은 경우에 유용합니다:
- 레거시 API를 다루는 경우
- 문서가 거의 없는 프로젝트에 합류한 경우
- 직접 만든 모바일 앱이나 웹 앱이 사용하는 API를 파악해야 하는 경우
- QA에게 실제 엔드포인트 목록을 전달하고 싶은 경우
- 현재 API를 예전 문서와 비교하고 싶은 경우
- 더 나은 문서를 작성하기 전에 빠르게 출발점이 필요한 경우
캡처한 트래픽은 실제 예시를 제공합니다. 해당 세션 동안 앱이 무엇을 보냈고 서버가 무엇을 반환했는지 보여 줍니다.
검사가 허용된 API, 앱, 계정만 캡처하세요. 캡처한 요청에는 비밀번호, 쿠키, 액세스 토큰, 개인 정보, 또는 비공개 회사 정보가 포함될 수 있습니다.
현재 mitmproxy를 이용한 방법
mitmproxy는 무료이면서 강력한 가로채기 프록시입니다. HTTP, HTTPS, WebSocket 트래픽을 캡처할 수 있습니다. 터미널 도구, Python, 자동화된 워크플로를 좋아하는 개발자에게 좋은 선택입니다.
mitmproxy는 기본 인터페이스에서 OpenAPI 내보내기를 간단한 내장 기능으로 제공하지 않습니다. 일반적인 해결책은 별도의 커뮤니티 프로젝트인 mitmproxy2swagger를 사용하는 것입니다.
일반적인 워크플로는 다음과 같습니다:
- mitmproxy 또는 mitmweb을 설치하고 실행합니다.
- 앱 또는 기기가 프록시를 통해 트래픽을 보내도록 설정합니다.
- 필요한 API 요청을 캡처합니다.
- 캡처한 트래픽을 mitmproxy 플로우 파일 또는 HAR 파일로 저장합니다.
mitmproxy2swagger와 필요한 Python 환경을 설치합니다.- 입력 파일, 출력 파일, API URL 접두사를 지정해 명령을 실행합니다.
- 첫 번째 YAML 결과를 열고, 감지된 경로 중 포함할 경로를 선택합니다.
- 명령을 다시 실행해 더 완전한 OpenAPI 문서를 만듭니다.
첫 번째 명령은 다음과 같을 수 있습니다:
mitmproxy2swagger \
-i capture.flow \
-o api-schema.yaml \
-p https://api.example.com/v1
첫 번째 실행에서는 가능성 있는 API 경로를 찾아냅니다. 그다음 YAML을 검토하고, 원하는 경로에서 ignore:를 제거한 뒤 경로 파라미터를 수정합니다. 그 후 도구를 다시 실행합니다. 선택 옵션을 사용하면 예시나 헤더를 추가할 수 있습니다.
이 방법은 유연합니다. 스크립트나 반복 가능한 빌드 프로세스에도 잘 맞습니다. 하지만 구성 요소가 여러 개라 관리할 것이 많습니다.
현재 방법의 어려운 점은 무엇인가요?
문제는 mitmproxy가 트래픽을 캡처하지 못하는 것이 아닙니다. 캡처는 할 수 있습니다. 어려움은 캡처에서 최종 OpenAPI 파일이 나오기까지의 모든 과정에 있습니다.
1. 도구를 두 개 이상 써야 합니다
mitmproxy로 트래픽을 캡처한 다음, OpenAPI를 만들기 위해 또 다른 프로젝트를 설치하고 실행해야 합니다. 각 도구마다 설정, 명령, 버전, 파일 형식이 다릅니다.
명령줄에 익숙한 사용자라면 괜찮을 수 있습니다. 하지만 신입 개발자나 QA 테스터에게는 간단해야 할 작업을 더디게 만들 수 있습니다.
2. 두 단계에 걸친 워크플로가 필요합니다
처음 생성된 파일이 최종 결과물은 아닙니다. 파일을 열고, 경로를 고르고, 값을 수정한 뒤 명령을 다시 실행해야 합니다.
이런 추가 검토는 유용하지만, 선택한 몇 개의 요청으로 빠르게 문서를 만들고 싶다면 번거롭게 느껴질 수 있습니다.
3. 전체 캡처에는 불필요한 요청이 많을 수 있습니다
브라우저나 모바일 앱은 분석 서비스, 이미지 서버, 기능 플래그, 인증 서비스 등 여러 호스트를 호출할 수 있습니다. 세션 전체를 내보내면 OpenAPI 결과에 원하는 API보다 훨씬 많은 내용이 들어갈 수 있습니다.
내보내기 전에 요청을 확인하고 유용한 것만 선택할 수 있다면 훨씬 수월합니다.
4. 예시에 개인 데이터가 포함될 수 있습니다
실제 트래픽은 실제 값을 담고 있어서 유용합니다. 하지만 그 값들은 위험할 수도 있습니다. 예시에 토큰, 이메일 주소, 내부 URL, 사용자 ID가 포함될 수 있습니다.
Git에 커밋하거나, 문서 사이트에 업로드하거나, 다른 사람과 공유하기 전에 항상 결과물을 검토하세요.
Proxyman으로 더 간단하게 하는 방법
Proxyman은 macOS 앱에 OpenAPI 내보내기 기능을 포함하고 있습니다. 트래픽을 캡처하고, 원하는 요청을 선택한 뒤, OpenAPI YAML 또는 HTML로 내보내면 됩니다.
별도로 설치할 변환기도 없고, 실행해야 할 두 번째 명령도 없습니다.
1단계: API 트래픽 캡처하기
최신 버전의 Proxyman for macOS를 다운로드해서 실행하세요. 앱 안에 표시된 설정 안내에 따라 Proxyman 인증서를 설치하고 신뢰하세요.
그다음 웹사이트, 시뮬레이터, 또는 모바일 앱을 사용하며 문서화하려는 동작을 수행하세요. 예를 들어 프로필 화면을 열어 사용자 정보를 불러오는 요청을 캡처할 수 있습니다.
Proxyman이 복호화된 요청과 응답을 볼 수 있는지 확인하세요.
깔끔한 결과를 얻으려면 한 번에 작은 사용자 흐름 하나만 캡처하세요. 시작하기 전에 현재 세션을 지울 수 있습니다.
2단계: 유용한 요청 선택하기
메인 테이블에서 API 호스트를 찾으세요. 문서에 포함해야 할 요청을 선택하세요.
모든 요청을 선택할 필요는 없습니다. 이미지, 분석, 그 밖에 API에 속하지 않는 서비스는 제외하세요.
같은 엔드포인트가 여러 번 나타난다면, 명확한 성공 응답 하나부터 시작하세요. 나중에 다른 요청이나 응답 구조를 보여 주는 예시가 생기면 그때 추가하면 됩니다.
3단계: OpenAPI 내보내기
선택한 요청을 마우스 오른쪽 버튼으로 클릭한 다음 다음 항목을 선택하세요:
Export → OpenAPI → OpenAPI YAML
파일을 저장할 위치를 선택하세요.
여기까지가 전체 내보내기 과정입니다. Proxyman은 선택한 요청과 응답을 바탕으로 OpenAPI 파일을 만듭니다.
4단계: YAML 파일 검토하기
YAML을 Swagger Editor나 평소 사용하는 코드 편집기에서 여세요. 경로, 메서드, 파라미터, 스키마가 올바른지 확인하세요.
생성된 문서는 출발점일 뿐입니다. 실제 트래픽은 한 세션에서 일어난 일만 보여 줍니다. 가능한 모든 오류 응답이나 서버가 지원하는 모든 선택 값까지 알 수는 없습니다.
5단계: 필요하면 읽기 쉬운 HTML로 내보내기
팀원이 API를 읽기만 하면 된다면, 대신 HTML로 내보내세요:
Export → OpenAPI → OpenAPI HTML
HTML은 빠른 검토나 비공개 전달에 유용합니다. 문서를 수정하고, 검증하고, 다른 OpenAPI 도구와 함께 사용할 계획이라면 YAML이 더 좋습니다.
OpenAPI를 위한 Proxyman vs mitmproxy
| 작업 | mitmproxy 워크플로 | Proxyman 워크플로 |
|---|---|---|
| HTTPS 트래픽 캡처 | 기본 제공 | 기본 제공 |
| 요청을 시각적으로 선택 | 대화형 인터페이스에서 사용 가능 | 메인 테이블에서 행 선택 |
| OpenAPI 생성 | 별도의 커뮤니티 도구 | Proxyman에 내장 |
| 설정 | 프록시와 Python 변환기 | Proxyman 앱 |
| 과정 | 캡처, 저장, 첫 실행, 편집, 재실행 | 캡처, 선택, 내보내기 |
| 출력 | OpenAPI YAML | OpenAPI YAML 또는 HTML |
| 적합한 용도 | 자동화 및 명령줄 워크플로 | 개발자와 QA가 빠르게 시각적으로 작업하기 |
mitmproxy는 여전히 강력한 도구입니다. 이미 Python으로 트래픽 캡처를 자동화하고 있다면, 그 워크플로가 프로젝트에 잘 맞을 수 있습니다. Proxyman은 먼저 명령줄 프로세스를 구축하지 않고도 세션을 검사하고 유용한 문서를 만들고 싶을 때 도움이 됩니다.
공유하기 전에 생성된 문서 확인하기
어떤 도구를 사용하든 다음 항목을 확인하세요:
- 비밀 정보를 제거하세요. 토큰, 쿠키, 비밀번호, 비공개 헤더, 이메일 주소, 개인 정보가 있는지 검색하세요.
- 경로 파라미터를 확인하세요.
/users/123같은 경로는/users/{id}로 바꿔야 할 수 있습니다. - 누락된 응답을 추가하세요. 캡처에는
200은 있어도400,401,404,500은 없을 수 있습니다. - 필수 필드를 확인하세요. 예시 하나만으로는 모든 필드가 필수인지 증명할 수 없습니다.
- 데이터 타입을 확인하세요. 한 응답에서 숫자처럼 보이는 값이 실제로는 문자열 ID일 수 있습니다.
- 인증 정보를 추가하세요. 실제 비밀 값을 그대로 복사하지 않고 예상되는 인증 방식을 설명하세요.
- 명확한 이름과 설명을 사용하세요. 생성된 스키마에도 사람이 작성한 설명이 여전히 필요합니다.
- 파일을 검증하세요. OpenAPI 편집기에서 열고 경고가 있으면 수정하세요.
결론
트래픽으로 OpenAPI를 생성하면 특히 원래 문서가 없을 때 많은 시간을 절약할 수 있습니다. mitmproxy도 별도의 변환기와 명령줄 워크플로를 통해 이 작업을 지원할 수 있습니다. 이 방식은 유연하지만, 사용자가 더 많은 단계를 직접 관리해야 합니다.
Proxyman은 기본 워크플로를 한 곳에 모아 둡니다. 요청을 캡처하고, 유용한 행을 선택하고, OpenAPI YAML 또는 HTML로 내보내면 됩니다. 문서를 빠르게 만들고 나중에 검토하려는 개발자와 QA 팀에게 부담 없이 시작할 수 있는 출발점입니다.
다음 단계
- Proxyman OpenAPI 내보내기 문서를 읽어 보세요
- 자세한 OpenAPI YAML 생성 튜토리얼을 따라 해 보세요
- iPhone 또는 iPad에서 HTTPS 트래픽을 캡처하는 방법을 알아보세요
- Android 에뮬레이터에서 HTTPS 트래픽을 캡처하는 방법을 알아보세요
- mitmproxy2swagger 프로젝트 가이드를 읽어 보세요
