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」をクリックします
- キーチェーンアクセスアプリケーションが自動的に開きます
- Charles Proxy証明書を検索して見つけます
- それをダブルクリックし、信頼設定を「常に信頼」に変更します
Windowsの場合：
- メニューバーから「Help → SSL Proxying → Install Charles Root Certificate」をクリックします
- インストールプロセス中に、証明書を「信頼されたルート証明機関」ストアにインストールします
SSLプロキシの有効化
証明書がインストールされたら、SSLプロキシを有効にする必要があります。
- Charlesのメニューバーから「Proxy → SSL Proxying Settings」を選択します
- 「Enable SSL Proxying」オプションをチェックします
3. キャプチャしたいドメイン名（ホスト）とポート（ポート443）をリストに追加します
4. また、*を使用してすべてのドメインを監視することもできます
設定が完了すると、Charlesは完全なHTTP/HTTPSリクエストとレスポンスをキャプチャできるようになります。
ヒント：アプリケーションがどのドメインを使用しているかわからない場合は、まずアプリケーションを自由に操作し、Charlesのセッションリストの「Encrypted」の下にあるリクエストを観察します。対応するドメインをメモし、それらをCharlesのSSL Proxying設定に追加してください。
アプリケーションからの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. 「プロジェクト設定 → データインポート → .harファイル」に移動します
3. CharlesからエクスポートしたHARファイルを選択します
Apidogはファイルの内容を自動的に解析し、検出されたエンドポイント情報をプレビューエリアに表示します。これには以下が含まれます。
- 検出されたエンドポイントの数
- リクエストメソッド（GET、POST、PUT、DELETEなど）
インポートプロセス中に、次のようなオプションを設定できます。
- どのモジュールにインポートするか
- 既存のエンドポイントを上書きするかどうか
インポートが完了すると、対応するモジュールでエンドポイントを表示できます。
APIドキュメントの洗練と最適化
自動生成されたAPIドキュメントは素晴らしい出発点ですが、ビジネス要件を満たすためには通常、さらなる調整が必要です。以下に一般的な改善点を示します。
- エンドポイント名の改善：一般的な名前をより記述的な名前に変更します
- パラメータ記述の追加：各パラメータの機能と使用時期を文書化します
- レスポンスコンポーネントの洗練：ビジネスロジックに合わせてレスポンスコンポーネントを整理します
- 例の追加：サンプルリクエストとレスポンスを含めます
- 認証の設定：エンドポイントが認証を必要とする場合、Apidogの環境変数または認証設定で対応する情報を構成します。これにより、テスト時にAPI呼び出しが正しく機能することが保証されます。
まとめ
パケットキャプチャツールを使用してHTTP/HTTPSトラフィックを記録し、それをApidogにインポートすることで、迅速にAPIドキュメントを生成し、テストのための実際のデータサポートを提供できます。
ブラウザ、デスクトップクライアント、モバイルアプリケーションのいずれであっても、この方法は、APIドキュメントの準備にかかる時間を大幅に短縮し、チームがAPIテストと開発を迅速に開始できるようにします。