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 を扱っている場合
ドキュメントがほとんどないプロジェクトに参加した場合
自分のモバイルアプリや Web アプリが使っている API を理解する必要がある場合
QA チームに、実際のエンドポイントの一覧を渡したい場合
現在の API を、古いドキュメントと比較したい場合
より良いドキュメントを書く前に、手早く出発点を用意したい場合

キャプチャした通信は、実際の例を提供します。そのセッション中にアプリが送ったものと、サーバーが返したものが分かります。

調査が許可されている API、アプリ、アカウントのみをキャプチャしてください。キャプチャしたリクエストには、パスワード、Cookie、アクセストークン、個人情報、社内の非公開情報が含まれている場合があります。

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 としてエクスポートします。

別途インストールする変換ツールも、実行する 2 つ目のコマンドもありません。

ステップ 1：API の通信をキャプチャする

最新版の Proxyman for macOS をダウンロードして開きます。アプリ内に表示される手順に従って、Proxyman の証明書をインストールし、信頼してください。

次に、Web サイト、シミュレータ、またはモバイルアプリを使い、ドキュメント化したい操作を実行します。例えば、プロフィール画面を開いて、ユーザーを読み込むリクエストをキャプチャします。

Proxyman で復号済みのリクエストとレスポンスが見えている状態にしてください。

結果をすっきりさせるには、一度に 1 つの小さなユーザーの操作だけをキャプチャしてください。開始する前に、現在のセッションをクリアしておくこともできます。

ステップ 2：必要なリクエストを選択する

メインテーブルで API のホストを探します。ドキュメントに含めるべきリクエストを選択します。

すべてのリクエストを選択する必要はありません。画像、アナリティクス、その他 API に含まれないサービスは除外してください。

同じエンドポイントが何度も現れる場合は、まず成功レスポンスを 1 つ選んでください。別のリクエストやレスポンスの形が見つかったら、後から例を追加できます。

ステップ 3：OpenAPI をエクスポートする

選択したリクエストを右クリックし、次を選択します：

Export → OpenAPI → OpenAPI YAML

ファイルの保存先を選択します。

選択した Proxyman のリクエストを OpenAPI YAML としてエクスポートする様子

これがエクスポートの全工程です。Proxyman は、選択したリクエストとレスポンスから OpenAPI ファイルを作成します。

ステップ 4：YAML ファイルを確認する

YAML を Swagger Editor または普段お使いのコードエディタで開きます。パス、メソッド、パラメータ、スキーマが正しいか確認してください。

Proxyman が生成した OpenAPI YAML ファイルを Swagger Editor で確認する様子

生成されたドキュメントは出発点にすぎません。実際の通信は、1 回のセッションで起きたことを示すだけです。考えられるすべてのエラーレスポンスや、サーバーがサポートするすべてのオプション値までは分かりません。

ステップ 5：必要に応じて読みやすい HTML をエクスポートする

チームメンバーが API を読むだけでよい場合は、代わりに HTML をエクスポートしてください：

Export → OpenAPI → OpenAPI HTML

HTML は、手早く確認したり、非公開で共有したりするのに便利です。ドキュメントを編集したり、検証したり、他の OpenAPI ツールと一緒に使ったりする場合は、YAML の方が適しています。

OpenAPI に関する Proxyman と mitmproxy の比較

作業	mitmproxy のワークフロー	Proxyman のワークフロー
HTTPS 通信をキャプチャ	組み込み	組み込み
リクエストを視覚的に選ぶ	対話型インターフェースで利用可能	メインテーブルで行を選択
OpenAPI を生成	別のコミュニティツール	Proxyman に組み込み
セットアップ	プロキシと Python 変換ツール	Proxyman アプリ
作業の流れ	キャプチャ、保存、最初の実行、編集、再実行	キャプチャ、選択、エクスポート
出力	OpenAPI YAML	OpenAPI YAML または HTML
最適な用途	自動化とコマンドラインのワークフロー	開発者と QA による、視覚的で素早い作業

mitmproxy は依然として強力なツールです。Python で通信のキャプチャを自動化している場合は、そのワークフローがプロジェクトによく合うかもしれません。一方、コマンドラインの処理を先に組まずに、セッションを確認して役立つドキュメントを作りたい場合は、Proxyman が役立ちます。

共有する前に生成されたドキュメントを確認する

どのツールを使う場合でも、次の点を確認してください：

機密情報を削除する。 トークン、Cookie、パスワード、非公開のヘッダー、メールアドレス、個人情報を検索して取り除きます。
パスパラメータを確認する。 /users/123 のようなパスは、/users/{id} に変更する必要があるかもしれません。
不足しているレスポンスを追加する。 キャプチャには 200 が含まれていても、400、401、404、500 は含まれていないかもしれません。
必須フィールドを確認する。 1 つの例だけでは、すべてのフィールドが必須かどうかは証明できません。
データ型を確認する。 あるレスポンスで数値に見える値が、実際には文字列の ID である場合があります。
認証の詳細を追加する。 実際の機密情報をコピーせず、想定される認証方法を記述してください。
わかりやすい名前と説明を付ける。 生成されたスキーマには、依然として人による説明が必要です。
ファイルを検証する。 OpenAPI エディタで開き、警告があれば修正してください。

まとめ

通信から OpenAPI を生成すると、特に元のドキュメントがない場合に、多くの時間を節約できます。mitmproxy は、別の変換ツールとコマンドラインのワークフローを使って、この作業をサポートできます。その方法は柔軟ですが、ユーザーが管理する手順が増えます。

Proxyman は基本的なワークフローを 1 か所にまとめています。リクエストをキャプチャし、必要な行を選択して、OpenAPI YAML または HTML をエクスポートします。ドキュメントを素早く作りたく、後で確認する予定の開発者や QA チームにとって、手軽な出発点です。

次のステップ

Proxyman の OpenAPI エクスポートのドキュメントをお読みください
詳しい OpenAPI YAML の生成チュートリアルに従ってください
iPhone や iPad から HTTPS 通信をキャプチャする方法を学ぶ
Android エミュレータから HTTPS 通信をキャプチャする方法を学ぶ
mitmproxy2swagger のプロジェクトガイドをお読みください

Noah Tran

2026年7月21日