Apidogで公開されたオンラインAPIドキュメントを開くと、各エンドポイントの隣に「試す」ボタンがあることに気づくでしょう。これをクリックすると、ページの右側にデバッグパネルがスライドして表示され、ドキュメント内で直接APIをテストできます。
しかし、この「デバッグ」機能の使いやすさは、プラットフォーム内でどれだけ適切に設定されているかに大きく依存します。適切なURL設定、認証設定、明確なパラメータ構造、完全なサンプルデータといった要素が、デバッグ体験に大きく影響します。
適切に設定されていない場合、ユーザーはパラメータの入力に多くの時間を費やしたり、API呼び出しに失敗したりする可能性があり、これは理想的とは言えません。
公開されたオンラインドキュメントが優れたデバッグ体験を提供できるよう、Apidogを効果的に設定する方法について議論しましょう。
適切なURL設定
オンラインドキュメントは見た目には問題なくても、「試す」ボタンをクリックしてリクエストを送信すると失敗することがよくあります。最も一般的な理由は、公開時に実行環境を選択せずに、エンドポイントが/pet/{petId}のようなパスのみを含んでいるためです。
これにより、プロトコルやホスト名のない不完全なリクエストURLとなり、リクエスト送信時にエラーが発生します。
これに対処するには、ユーザーが正しいURLにアクセスできるようにする必要があります。Apidogは、ニーズに応じてオンラインドキュメントのURLを設定する3つの方法を提供しています。
1. ベースURLを使用する
これは推奨されるアプローチです。エンドポイントでは/pet/{petId}のようなパスのみを定義し、「環境管理」セクションで完全なサービスアドレス（例：https://product.example.com）をベースURLとして設定します。
APIドキュメントを公開する際には、適切な実行環境を選択します。ApidogはベースURLとエンドポイントパスを自動的に結合します。複数の実行環境を定義することもでき、それぞれに独自のベースURLを設定できます。
オンラインドキュメントでは、ユーザーはドロップダウンリストから環境を素早く切り替えることができ、すべてのエンドポイントURLがそれに応じて更新されます。これにより、異なる環境でのAPIの検証が便利になります。
注意: プロトコルの問題に注意してください。多くのブラウザは、HTTPSページからHTTP APIを呼び出すことを制限しています。APIがHTTPを使用している場合、HTTPSドキュメントページでデバッグする際に、ユーザーはクロスプロトコルの問題に遭遇する可能性があります。
2. エンドポイントに完全なURLを含める
もう一つの選択肢は、https://product.example.com/pet/{petId}のように、エンドポイントに完全なURLを直接指定することです。
これにより、選択された実行環境に関わらず完全なリクエストURLが表示されます。ただし、サーバーアドレスの変更を管理する際に、各エンドポイントを個別に更新する必要があるため、煩雑になります。したがって、この方法はあまり推奨されません。
3. URLで変数を使用する
ユーザーがデバッグのためにURLをカスタマイズできるようにしたい場合は、変数を使用できます。例えば、「環境管理」セクションで環境変数BaseURLを作成し、ベースURLで{{BaseURL}}として参照します。
オンラインドキュメントでは、ユーザーは変数名をクリックして、希望のURLに修正できます。
あるいは、{{BaseURL}}/pet/{petId}のように、エンドポイント内で直接変数を定義することもできます。
オンラインドキュメントのその特定のエンドポイントでは、ユーザーはリクエストを送信するために変数の値を設定できます。
ドキュメントを公開する前に、環境内の「初期値」に機密情報（例：認証情報）が含まれていないことを確認してください。これらの値は公開されたドキュメントに含まれ、プライバシーリスクをもたらす可能性があります。
適切な認証設定
基本認証の設定
エンドポイントリクエストの成功には、多くの場合認証が必要です。Apidogは、ベアラートークン、APIキー、OAuth2.0、基本認証など、様々な認証タイプをサポートしています。
認証は、セキュリティスキームを使用するか、手動で設定することで、エンドポイントまたはフォルダレベルで設定できます。
例えば、ベアラートークンを認証タイプとして使用する場合、オンラインドキュメントのデバッグパネル上部に「トークン」フィールドが表示されます。ユーザーは「Bearer」プレフィックスを手動で追加することなく、トークン値を直接入力できます。Apidogがこれを自動的に処理するため、認証ヘッダーを手動で追加するよりも便利です。
この設定の利点は、認証情報を複数のエンドポイント間で共有できることです。複数のエンドポイントが同じセキュリティスキームまたはタイプを使用する場合、資格情報を一度入力するだけで済みます。資格情報の更新は、関連するすべてのエンドポイントに自動的に適用されます。
認証情報は暗号化され、ユーザーのブラウザにローカルに保存され、セッションごとに管理され、タブやウィンドウ間で共有されます。ブラウザが閉じられるとクリアされるため、公開されたドキュメントで機密情報が漏洩するリスクが軽減されます。
OAuth2.0設定
OAuth2.0認証の場合、デバッグ中にユーザーが直接トークンを生成できるようにしたい場合は、プロジェクト内で認証サーバーの詳細（例：認証URL、トークンURL）を設定します。
OAuth2.0セキュリティスキームを使用する場合、ユーザーはデバッグ中にクライアントID、クライアントシークレットなどを入力する必要があります。ポップアップが表示され、認証プロセスをガイドし、取得されたaccess_tokenは後続のAPIリクエストに自動的に適用されます。
明確なパラメータ構造の設計
デバッグパネルでのパラメータ表示
デバッグパネルは、エンドポイントの設計に基づいてパラメータセクションをインテリジェントに表示します。例えば、エンドポイントがパスパラメータのみを定義している場合、デバッグパネルはパスセクションのみを表示し、不要なクエリやボディセクションは表示しません。
この明確さにより、ユーザーは無関係なセクションに気を取られることなく、どのパラメータを入力すべきかを理解しやすくなります。
例を提供する
エンドポイントを設計する際には、各パラメータの型と必須属性を正確に定義します。明確な説明と例を含めることで、これらがデバッグパネルに事前入力され、使いやすさが向上します。
不要なヘッダーを避ける
エンドポイントがボディパラメータを定義している場合、Content-Type: application/jsonのようなヘッダーを手動で追加する必要はありません。Apidogはリクエスト中にこのようなヘッダーを自動的に処理します。
同様に、認証が設定されている場合、ヘッダーでそれを重複させないでください。認証設定が優先され、競合するヘッダー設定を上書きします。
包括的なリクエスト例を提供する
複雑なJSONリクエストボディを持つエンドポイントの場合、設計中に複数のリクエストボディ例を提供します。
ユーザーはデバッグパネルのドロップダウンメニューからこれらの例を選択でき、時間とエラーを削減できます。
サンプルデータが実際のシナリオに密接に似ていることを確認しますが、機密情報を含めないようにしてください。ユーザーは必要に応じてこれらの例を修正できます。
明確なレスポンス例を設定する
リクエスト送信後、デバッグパネルにはステータスコード、ヘッダー、ボディを含む完全なレスポンスが表示されます。ドキュメント作成者として、ユーザーが考えられる結果を理解できるよう、明確なレスポンス例を設定してください。
各エンドポイントに対して、成功（200）、不正なリクエスト（400）、未認証（401）など、複数のレスポンス例を提供します。
エラーレスポンスには特に注意を払い、異なるシナリオにおけるエラーコードとメッセージ形式を明確に説明してください。これにより、ユーザーはデバッグ中に問題を迅速に特定し、解決するのに役立ちます。
統合のためのサンプルコードを提供する
Apidogは一般的なプログラミング言語のサンプルコードを自動生成しますが、生成されたコードがビジネスニーズに完全に合致しない場合があります。そのような場合は、例をカスタマイズしてください。
「プロジェクト設定 -> エンドポイント機能設定 -> リクエストコードサンプル」で、自動生成される例が必要な言語を設定できます。
さらに、「エンドポイント説明」セクションで、特定のエンドポイントのカスタムサンプルコードを記述することもできます。
これにより、ユーザーはオンラインドキュメントで自動生成された例とカスタム例の両方を確認でき、統合が容易になります。
まとめ
オンラインドキュメントのデバッグ体験は、適切な設定に大きく依存します。URL、認証、パラメータ構造、および例を慎重に設定することで、ユーザーは技術的な詳細に煩わされることなく、APIを迅速に使い始めることができます。