ApidogでAPI仕様からクライアントコードを生成する方法

エンドポイントが定義されており、それをアプリから呼び出したいと考えているとします。仕様を動作するコードに変換する部分は面倒です。正しいURL、ヘッダー、認証トークン、クエリ文字列のすべてをrequestsコールまたはfetchに組み込む作業です。一文字でも間違ってコピーすると、なぜサーバーが401を返すのか、20分も悩むことになります。

その定型文を手書きする必要はありません。APIがApidogで設計されている場合、プラットフォームはエンドポイント仕様を読み取り、作業している言語ですぐに貼り付けられるリクエストスニペットを提供します。素早いターミナルでの確認にはcURL、スクリプトにはPython requests、フロントエンドにはJavaScript fetchまたはAxiosです。このガイドでは、実際のエンドポイントからそのコードを生成する方法、スニペットに実際の値を含めるために最初にリクエストを送信するタイミング、そして仕様が変更されたときに生成されたコードの正確性を保つ方法について説明します。より広範な選択肢については、APIコード生成ツールのまとめで全体像を把握できますが、ここでは組み込みジェネレーターに焦点を当てて実践的に解説します。

ボタン

この考え方は、OpenAPI Specificationの背後にある原則と同じく、仕様が唯一の信頼できる情報源であるというものです。一度定義を正しく行えば、それに基づいてリクエストコードが生成されます。

クライアントコードジェネレーターが実際にすること

Apidogは、エンドポイント定義を言語バリアントごとのリクエストスニペットに変換します。GET /ordersを指し、PythonとRequestsライブラリを選択すると、仕様が宣言するヘッダーとパラメーターでそのパスにアクセスする呼び出しを記述します。これはリクエストジェネレーターです。選択した言語とHTTPライブラリの構文で、1つの呼び出しのコードを生成します。

1点について期待を正しく設定してください。この機能は、エンドポイントの要求またはクライアントコードを生成するものであり、完全なSDKやバージョン管理されたクライアントライブラリパッケージを生成するものではありません。cURLの行、Python requestsブロック、またはコードに挿入するJS fetchスニペットが必要な場合は、それが得られます。ドキュメントには完全なライブラリジェネレーターについては説明されていないため、モデルやページネーションヘルパーが組み込まれたダウンロード可能な型付きSDKを期待しないでください。

これは、デザインファーストのAPI開発ワークフローと自然に組み合わせられます。契約を定義し、そこから直接リクエストコードを生成することで、すべてのコンシューマーがSlackに貼り付けられたスクリーンショットではなく、同じ正確な定義から開始できます。

ジェネレーターを開く2つの方法

Apidogは、同じ機能への2つのエントリーポイントを提供します。現在いる場所に合わせて、どちらかを使用してください。

1つ目はドキュメントからです。APIのドキュメントタブを開き、右側にあるクライアントコードを生成ボタンをクリックします。これは、エンドポイントのドキュメントを読んでいて、その呼び出しを必要とするときに最も速いパスです。

2つ目はランナーからです。APIの実行タブで、コードアイコン</>をクリックします。これはリクエストを作成して送信する場所の隣にあるため、既に呼び出しをテストしている場合に自然な選択肢となります。

どちらも同じパネルを開きます。そこから言語とバリアントを選択すると、Apidogがスニペットを記述します。

GET /orders のPythonクライアント呼び出しを生成する

ここでは、リアルなエンドポイントを使用した完全なフローを紹介します。顧客の注文をリスト表示し、ステータスでフィルタリングし、ページネーションを行うGET /orders呼び出しです。

ステップ1：エンドポイントを開き、言語を選択する

エンドポイントのドキュメントタブを開き、クライアントコードを生成をクリックします。パネルでターゲットを選択します。Apidogは多数の言語とバリアントをサポートしているため、スタックに正確に合わせることができます。

シェル: cURL, cURL-Windows, Httpie, wget, PowerShell
JavaScript: Fetch, Axios, jQuery, XHR, Native, Request, Unirest
Python: http.client, Requests
Java: Unirest, OkHttp
Go: Native
PHP: cURL, Guzzle, pecl_http, HTTP_Request2
その他: Swift (URLSession), C (libcurl), C#, Objective-C, Ruby, OCaml, Dart, R, および生のHTTPオプション

この例では、PythonとRequestsバリアントを選択します。Apidogは仕様から次のようなものを生成します。

import requests

url = "https://api.example.com/orders"

querystring = {"status": "shipped", "page": "1"}

headers = {"Accept": "application/json"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

これをコピーしてスクリプトに貼り付ければ、動作する呼び出しになります。これがデザインファーストのアプローチです。スニペットは、エンドポイントが宣言する内容を正確に反映しています。

ステップ2：仕様のみのスニペットに含まれる内容を把握する

貼り付ける前に理解しておくべき注意点があります。API仕様から直接生成されたコードには、API仕様のみが含まれ、実際のリクエストパラメーター値や認証トークンは含まれません。呼び出しの形式と、仕様で定義されている例の値は取得できますが、保護されたエンドポイントに実際に到達するために必要なライブのAuthorization: Bearer ...ヘッダーは含まれません。

認証がない呼び出しの場合や、トークンを自分で入力する場合は問題ありません。保護されたGET /ordersの場合、コードに実際の値が必要になります。

ステップ3：実際のリクエストを送信して実際の値をキャプチャする

実際のリクエストパラメーター値と認証情報を含むスニペットを取得するには、まずリクエストを送信し、次に実際のリクエストタブからコードを読み取ります。

デザインファーストで作業している場合、これは簡単です。編集タブでエンドポイントを定義し、実行タブをクリックすると、リクエストパラメーターが仕様から自動的に入力されます。手動で設定したい場合（リクエストファーストモード）は、代わりに実行タブでリクエストパラメーターを手動で入力します。いずれの方法でも、認証トークンを追加し、送信をクリックしてリクエストを送信します。

応答が返されたら、実際のリクエストタブに切り替え、下にスクロールしてクライアントコードを見つけます。これで、生成されたスニペットには、実際に送信された具体的な値と認証ヘッダーが含まれます。

import requests

url = "https://api.example.com/orders"

querystring = {"status": "shipped", "page": "1"}

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer sk_live_51H8xY2..."
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())

これが2つのパスの違いです。デザインファーストモードでは、仕様からパラメーターが自動入力されます。リクエストファーストモードでは、手動で入力できます。どちらも送信をクリックすると、同じ実際のリクエストスニペットが提供されます。上記のような実際のトークンは秘密として扱い、Gitにコミットするものには含めないでください。Stripeのドキュメントがライブキーについて推奨しているのと同じ注意がここに当てはまります。

POSTおよびPUTのリクエストボディの処理

GET /ordersにはボディがありませんが、POST /ordersやPUT /orders/{id}のコードを生成する瞬間には、スニペットにリクエストボディが必要です。Apidogは、生成前に実行タブでボディを構築するのに役立ちます。

JSONまたはXMLボディの場合、2つのソースがあります。エンドポイント仕様から事前定義された例を使用するか、自動生成をクリックしてスキーマに一致するボディ構造を作成します。自動生成ドロップダウンには2つのモードがあります。

例: 事前定義されたリクエストボディの例を手動で選択します。
毎回生成: スマートモックルールに従って、使用するたびにデータを再生成し、常に新鮮でスキーマに有効な値を取得します。

自動生成設定のサブオプション（まず例の値を使用、まずデフォルトの値を使用、モック値を使用、フィールド名のみを生成、リクエスト例を使用）を使用して、データの生成方法を制御できます。仕様に良い例があり、それを尊重したい場合はまず例の値を使用を選択し、すべてのフィールドにリアルな生成データが必要な場合はモック値を使用を選択します。

バージョンに関する注意：リクエストボディの自動生成オプションはApidog 2.7.0以降が必要です。表示されない場合は、アプリを更新してください。OpenAPIからAPIドキュメントを自動生成することで得られるような、例を含む適切に指定されたスキーマを使用すると、このステップでほぼ手動編集なしでクリーンなボディを生成できます。

新しいタイムスタンプやランダムな注文IDなど、リクエストごとに変化する値が必要な場合は、値をハードコーディングするのではなく、動的な値を挿入します。パラメーター入力ボックスの横にある魔法の杖アイコンをクリックするか、JSONまたはXMLリクエストボディ内で動的な値を挿入ボタンを使用します。ボディの準備ができたら、送信をクリックし、以前と同様に実際のリクエストタブから完成したスニペットを読み取ります。

リクエストスニペットとビジネスモデル呼び出しの使い分け

簡単な判断：どれくらいのコードをコピーすべきでしょうか？

1回限りの作業を行う場合は、単一のリクエストスニペット（cURL、fetch、生のrequests.get）を使用してください。エンドポイントが403を返す理由のデバッグ、チケットでの再現可能な呼び出しの共有、ターミナルでの素早い確認、または自身のドキュメントへの例の貼り付けなどです。これは自己完結型であり、周囲の構造を必要としません。

呼び出しが実際のアプリケーションロジック内に存在する場合は、より完全なビジネスモデルスタイルのコード（ヘッダー、パラメーター、応答処理が記述されたAxiosまたはrequestsブロック）に傾倒してください。GET /ordersが3か所から呼び出されるサービスモジュール内に配置される場合、関数でラップし、エラー処理を追加し、再利用できる構造化されたバージョンが必要になります。ジェネレーターは、選択したバリアントに応じて両方の形状を提供します。コードが配置される場所に合わせて形状を一致させてください。

プロジェクト全体で同じ認証情報を使用して同じエンドポイントを呼び出す場合、共有部分を一元化する方がクリーンであることがよくあります。Apidogでグローバルパラメーターを設定する方法に関するガイドでは、ヘッダーと変数を一度定義する方法を示しており、生成されたすべての呼び出しが、各スニペットでトークンを繰り返す代わりにそれらを継承するようにできます。

仕様ファーストの習慣で生成コードの正確性を保つ

生成されたコードは、その背後にある仕様と同じくらい正確です。GET /ordersにregionクエリパラメータを追加する変更を行い、再生成を忘れると、コピーしたスニペットは静かに間違ったものになります。この問題を解決するには、仕様を維持すべきものとして扱い、コードを必要に応じて再生成する派生出力として扱うことです。Apidogの仕様ファーストモードは、定義を権威あるものとして保持するため、生成するリクエストコードは常に現在の契約を反映し、古いものを反映することはありません。

スニペット自体の構文については、Apidogが生成するJavaScriptバリアントを理解したり微調整したりしたい場合に、Fetch APIに関するMDNドキュメントが信頼できるリファレンスとなります。

Apidog CLIでワークフローを自動化する

コード生成自体はGUI操作であり、パネルからスニペットをコピーするもので、クライアントコードを出力する独立したCLIコマンドはありません。Apidog CLIが優れているのは、生成に依存する2つの要素を維持することです。それは、最新の仕様と、生成されたクライアントが実際に機能することを証明する合格テストです。

npm install -g apidog-cli (Node.js v16+) でインストールし、認証します。

apidog login --with-token <YOUR_ACCESS_TOKEN>

新しい仕様の変更をインポートして生成コードを最新の状態に保ち、クライアントが呼び出すエンドポイントを実行する保存されたテストシナリオを実行します。

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli

ここで-tはテストシナリオID、-eは環境ID、-rはレポーター（cli、html、またはjunit）です。これをApidog CLI GitHub Actionsガイドで説明されているようにパイプラインに組み込むことで、すべてのプッシュでGET /ordersが仕様の約束通りに動作するかどうかを検証し、誰かがクライアントを再生成する前に壊れた契約がビルドを失敗させます。CLIはクライアントコードを記述しませんが、そのコードが構築されている契約を保護します。

よくある質問 (FAQ)

生成されたコードにAPIキーとトークンは含まれますか？

デフォルトでは含まれません。API仕様のみから生成されたコードには、実際のパラメーター値や認証は含まれず、仕様のみが含まれます。実際のトークンと値を含むスニペットを取得するには、まずリクエストを送信し、次に実際のリクエストタブからコードを読み取ってください。そのスニペット内のトークンは秘密として扱ってください。

Apidogはどの言語とライブラリのコードを生成できますか？

幅広いセットです。シェル (cURL, Httpie, wget, PowerShell)、JavaScript (Fetch, Axios, jQuery, XHR など)、Python (http.client および Requests)、Java (Unirest, OkHttp)、Go、PHP、Swift、C、C#、Ruby、Dart、R、その他。ジェネレーターパネルで言語と特定のバリアントを選択します。

リクエストボディの自動生成オプションが表示されないのはなぜですか？

これらのオプションにはApidog 2.7.0以降が必要です。アプリを更新すると、JSONまたはXMLボディを作成する際に実行タブに表示されます。利用可能になると、自動生成ドロップダウンに例と毎回生成が表示され、値の生成方法に関する設定サブオプションも利用できます。

クライアントコード生成は有料機能ですか？

Apidogのドキュメントでは、クライアントコード生成について無料版と有料版、クラウド版とセルフホスト版の区別はしていません。唯一のバージョン要件として言及されているのは、自動生成のリクエストボディオプションにはバージョン2.7.0以降が必要であるという点だけです。Apidogをダウンロードして、有料プランなしでジェネレーターを試すことができます。

生成された呼び出しが実際に動作することを確認するにはどうすればよいですか？

スニペットを生成した後、保存されたテストでエンドポイントを検証します。Apidogでテストシナリオを作成する方法に関するチュートリアルでは、その構築方法が示されており、CLIはCIで実行できるため、誰かがクライアントを再生成する前に、契約が壊れている場合にビルドが失敗します。

まとめ

Apidogでのクライアントコード生成は、エンドポイントの仕様を作業している言語ですぐに貼り付けられるリクエストに変換します。そして、実際のリクエストタブは、空のテンプレートではなく、実際の値と認証をスニペットに組み込むための秘訣です。仕様を権威あるものとして保持し、変更があった場合は再生成し、保存されたテストで呼び出しが引き続き機能することを確認しましょう。Apidogをダウンロードして、GET /ordersエンドポイントを定義し、数回のクリックで動作するクライアント呼び出しをコピーしてください。