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

エンドポイントは定義済みで、アプリケーションから呼び出したいとします。仕様を実行可能なコードに変換する作業では、URL、ヘッダー、認証トークン、クエリ文字列を requests や fetch に正確に組み込む必要があります。1文字でも間違えると、401 の原因調査に時間を使うことになります。

今すぐApidogを試す

この定型コードを手書きする必要はありません。APIを Apidog で設計している場合、エンドポイント仕様からそのまま貼り付けられるリクエストスニペットを生成できます。ターミナル確認用のcURL、スクリプト用のPython requests、フロントエンド用のJavaScript fetch やAxiosなどを選択できます。

この記事では、実際のエンドポイントからコードを生成する手順、実際の認証情報やパラメーターを含める方法、仕様変更後もスニペットを正しく保つ運用を解説します。より広い選択肢を確認したい場合は、APIコード生成ツールのまとめも参照してください。

仕様を唯一の信頼できる情報源として扱う考え方は、OpenAPI Specificationの原則とも一致します。仕様を正しく定義すれば、その定義を基にリクエストコードを生成できます。

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

Apidogは、エンドポイント定義を選択した言語・HTTPライブラリ向けのリクエストスニペットに変換します。

たとえば GET /orders に対してPythonのRequestsを選ぶと、仕様で定義されたパス、ヘッダー、パラメーターを使う呼び出しコードが生成されます。

これは1つのHTTPリクエストを生成する機能です。完全なSDK、バージョン管理されたクライアントライブラリ、モデル、ページネーションヘルパーを含むパッケージを出力する機能ではありません。

次のような用途に向いています。

• cURLでAPIを素早く検証する
• Pythonスクリプトに requests 呼び出しを追加する
• フロントエンドに fetch またはAxiosの呼び出しを追加する
• チケットやドキュメントに再現可能なリクエスト例を共有する

このワークフローは、デザインファーストのAPI開発と組み合わせると効果的です。契約を先に定義し、その契約からコードを生成すれば、チーム全体が同じAPI定義を基準に実装できます。

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

Apidogでは、同じコード生成パネルを2つの場所から開けます。

方法1: ドキュメントタブから開く

エンドポイント仕様を確認しながらコードを取得したい場合はこちらです。

1. APIのドキュメントタブを開く
2. 右側のクライアントコードを生成をクリックする
3. 言語とライブラリを選択する
4. スニペットをコピーする

方法2: 実行タブから開く

実際にリクエストをテストした直後にコードを取得したい場合はこちらです。

1. APIの実行タブを開く
2. コードアイコン </> をクリックする
3. 言語とライブラリを選択する
4. スニペットをコピーする

どちらの方法でも同じコード生成パネルが開きます。

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 を選択します。

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: 仕様から生成したスニペットの範囲を理解する

仕様だけから生成したコードには、通常、次の情報が含まれます。

• HTTPメソッド
• URLとパス
• クエリパラメーターの構造
• 仕様で定義されたヘッダー
• リクエストボディのスキーマや例

一方で、実際に実行したリクエスト固有の値は含まれません。

• 実際の認証トークン
• 実行時に入力したパラメーター
• 動的に生成された値

保護されたエンドポイントでは、実際の Authorization: Bearer ... ヘッダーを含むスニペットが必要になることがあります。

ステップ3: リクエストを送信して実際の値を含める

実際に送信したパラメーターや認証情報を含むコードが必要な場合は、先にリクエストを実行します。

1. 実行タブを開く
2. クエリパラメーターやヘッダーを入力する
3. 認証トークンを設定する
4. 送信をクリックする
5. 応答後、実際のリクエストタブを開く
6. クライアントコードをコピーする

デザインファーストで作業している場合、編集タブで定義したパラメーターは実行タブへ自動入力されます。リクエストファーストの場合は、実行タブで値を手動入力します。

送信後のスニペットには、実際に使用した値と認証ヘッダーが含まれます。

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())

実際のトークンを含むコードは、そのままGitにコミットしないでください。トークンは環境変数やシークレット管理機能で扱います。Stripeのキー管理に関するドキュメントで説明されているライブキーと同様に、秘密情報として扱う必要があります。

例えば、アプリケーションコードでは次のように環境変数から読み込みます。

import os
import requests

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

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {os.environ['API_TOKEN']}"
}

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

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

orders = response.json()

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

GET /orders にはリクエストボディがありません。しかし、POST /orders や PUT /orders/{id} ではJSONやXMLのボディが必要です。

Apidogでは、生成前に実行タブでボディを準備できます。

JSONまたはXMLのボディには、次の2つのソースがあります。

1. エンドポイント仕様で定義されたリクエスト例
2. 自動生成によるスキーマ準拠のデータ

自動生成には次のモードがあります。

• 例: 事前定義されたリクエストボディ例を選択する
• 毎回生成: スマートモックルールに従い、使用するたびに新しいスキーマ準拠データを生成する

さらに、自動生成設定で値の優先順位を制御できます。

• まず例の値を使用
• まずデフォルトの値を使用
• モック値を使用
• フィールド名のみを生成
• リクエスト例を使用

仕様に意味のある例が定義されている場合は、まず例の値を使用が適しています。すべてのフィールドに生成値が必要な場合は、モック値を使用を選択します。

リクエストボディの自動生成機能にはApidog 2.7.0以降が必要です。表示されない場合はアプリを更新してください。

スキーマと例を適切に定義しておくと、OpenAPIからAPIドキュメントを自動生成するワークフローと同様に、手動編集を減らしながら一貫したリクエストボディを作成できます。

タイムスタンプやランダムな注文IDなど、リクエストごとに変わる値には、固定値ではなく動的な値を使用します。

1. パラメーター入力欄の横にある魔法の杖アイコンをクリックする
2. または、JSON/XMLボディ内の動的な値を挿入を使用する
3. ボディを準備して送信をクリックする
4. 実際のリクエストタブから最終的なスニペットを取得する

リクエストスニペットとアプリケーションコードの使い分け

コピーしたコードをどこまでそのまま使うかは、用途で判断します。

単発の確認には単一スニペットを使う

次の用途では、cURL、fetch、requests.get などの自己完結したスニペットが適しています。

• 403 や 401 の原因を調査する
• チケットに再現手順を貼る
• ターミナルからAPIを確認する
• 社内ドキュメントにリクエスト例を載せる

アプリケーションでは関数にラップする

同じ GET /orders を複数箇所から呼び出す場合は、生成されたコードをサービス関数として整理します。

import os
import requests


class OrdersClient:
    def __init__(self, base_url: str, token: str):
        self.base_url = base_url
        self.headers = {
            "Accept": "application/json",
            "Authorization": f"Bearer {token}"
        }

    def list_orders(self, status: str, page: int = 1):
        response = requests.get(
            f"{self.base_url}/orders",
            headers=self.headers,
            params={
                "status": status,
                "page": page
            },
            timeout=10
        )
        response.raise_for_status()
        return response.json()


client = OrdersClient(
    base_url="https://api.example.com",
    token=os.environ["API_TOKEN"]
)

orders = client.list_orders(status="shipped")

この形にすると、認証、タイムアウト、エラー処理を一元化できます。

複数のエンドポイントで共通ヘッダーや変数を使用する場合は、Apidogでグローバルパラメーターを設定する方法も有効です。共通値を一度定義すれば、各スニペットにトークンを繰り返し書く必要がありません。

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

生成コードの正確性は、元になる仕様の正確性に依存します。

たとえば GET /orders に region クエリパラメーターを追加した後、コードを再生成しなければ、既存のスニペットは古い契約を参照し続けます。

運用では次を徹底します。

1. API変更時に仕様を更新する
2. 変更されたエンドポイントのスニペットを再生成する
3. 実際のリクエストまたは保存済みテストで動作を検証する
4. アプリケーション側の共通クライアント実装を更新する

Apidogの仕様ファーストモードを使うと、定義を権威ある情報源として維持しやすくなります。

JavaScriptの生成コードを調整する場合は、MDNのFetch APIドキュメントを参照すると、fetch のオプションやレスポンス処理を確認できます。

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

クライアントコード生成はGUIで行い、パネルからスニペットをコピーします。クライアントコードを直接出力する独立したCLIコマンドはありません。

ただし、Apidog CLIは、生成コードが依存する以下の要素を維持するために役立ちます。

• 最新のAPI仕様
• エンドポイントが実際に動作することを示すテスト結果

まずCLIをインストールします。

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のようにCIパイプラインへ組み込めば、プッシュごとに GET /orders が契約どおり動作するかを検証できます。

CLI自体はクライアントコードを生成しませんが、クライアントコードが依存するAPI契約をテストで保護できます。

よくある質問（FAQ）

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

デフォルトでは含まれません。仕様から生成したコードには、仕様で定義された構造や例が含まれます。

実際のトークンや実行時パラメーターを含むコードが必要な場合は、先にリクエストを送信し、実際のリクエストタブからコードを取得してください。取得したトークンは秘密情報として扱い、Gitにコミットしないでください。

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のドキュメントでは、クライアントコード生成について無料版・有料版、クラウド版・セルフホスト版の区別は説明されていません。明示されているバージョン要件は、リクエストボディの自動生成にApidog 2.7.0以降が必要という点です。

Apidogをダウンロードして、ジェネレーターを試すことができます。

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

スニペットを生成した後、保存済みテストでエンドポイントを検証してください。Apidogでテストシナリオを作成する方法では、テストシナリオの作成方法を確認できます。

CLIをCIで実行すれば、誰かがクライアントコードを再生成する前に、壊れたAPI契約をビルド失敗として検出できます。

まとめ

Apidogのクライアントコード生成を使うと、エンドポイント仕様をPython、JavaScript、cURLなどの貼り付け可能なリクエストコードに変換できます。

実装時は、次の流れを使うと効率的です。

1. API仕様を定義する
2. ドキュメントタブまたは実行タブからコードを生成する
3. 実際の値や認証が必要ならリクエストを送信する
4. 実際のリクエストタブから最終スニペットを取得する
5. 秘密情報を環境変数へ移す
6. 仕様変更時にコードを再生成し、テストで検証する

Apidogをダウンロードして、GET /orders のようなエンドポイントを定義し、数クリックで動作するクライアント呼び出しを生成してみてください。