HTTP Archive (HAR)¶
すべての API に OpenAPI/Postman/Swagger 仕様があるわけではありません。コード自体が唯一の仕様である場合もあります。API とのトランザクションを HTTP Archive (.har) ファイルとして記録し、記録を OpenAPI 仕様に変換することで、仕様が存在しない API でもテストできます。これによって仕様が存在しない API のテストが可能になるいっぽう、コードから生成された仕様または手作業でメンテナンスされている仕様と比較すると、変換された仕様は正確性において不利な点があります。
HAR ファイルに機密情報が含まれる可能性¶
⚠️ HAR ファイルにはクライアント/ブラウザーとターゲット API の間で送信された あらゆるもの が含まれます。これには Authorization、Cookie なども含まれます。あらかじめ機密情報を除去しないかぎり、.har ファイルを永続化したり変換したりすることは推奨されません。
.HAR ファイルから OpenAPI 3 仕様への変換¶
Info
mapi 2.6.16 以降が必要です。
他のフォーマットから OpenAPI 3 仕様に変換するには、mapi convert コマンドを使用します。
たとえば、次のコマンドは記録ファイル recording.har を OpenAPI 仕様 openapi.yaml に変換します。
mapi convert har recording.har --host "127.0.0.1:8080" --base-path "api/v1" --out openapi.yaml
引数を確認しましょう。
--host "127.0.0.1:8080"変換処理は記録から API の URL を推測しようとします。記録に複数の URL へのリクエストが含まれている場合、--hostオプションを指定して、特定のホストからのリクエストだけを変換するよう制限できます。--base-path "api/v1"API に共通ベースパスがある場合、このオプションを指定すると、すべてのリクエスト URL から共通接頭辞が除去されます。これにより、変換後の仕様の正確性が大幅に向上する可能性があります。--out opennapi.yamlこの引数は、既存のファイルopenapi.yamlが存在する場合、変換後の仕様で上書きします。この引数を指定しない場合、変換結果はターミナルの標準出力に出力します。
Info
利用可能なすべてのオプションを表示するには、mapi convert --help コマンドを実行します。
変換が成功したら、変換後のファイルを検査し、必要と考えられる修正を行ったり、即座に新規ランを開始したりできます。
ブラウザーを使用した .HAR 記録ファイルの作成¶
API とやりとりする Web フロントエンドがある場合、Web サイトを操作してさまざまなユース ケースを実行し、フロントエンドからアクセスした機能に基づいて API 通信の記録を構築することで HTTP Archive を記録できます。
現在の多くのブラウザーは、通信の記録および HAR ファイルのエクスポートをサポートしています。 ブラウザー固有の詳細については https://toolbox.googleapps.com/apps/har_analyzer/ を参照してください。
プロキシを使用した .HAR 記録ファイルの作成¶
Web フロントエンドでは API に適切なリクエストを行って有効な OpenAPI 仕様を作成できない場合もあります。CLI、自動テスト スイート、手動での curl の呼び出しの集合など、適切なリクエストを行うことができる他のツールが存在する場合もあるでしょう。その場合、プロキシを使用してすべてのトラフィックを記録し、HAR ファイルを作成できます。
以下のツールにはそのような機能があります。
Info
トラフィックを記録して HAR ファイルとしてエクスポートするのに役立つツールは他にも多く存在します。上記に含めるべきツールがあれば、お知らせください: support@forallsecure.com