Apidogは各エンドポイントに複数のリクエストボディ例を追加することをサポートしています。これにより、APIドキュメントがより役立ち、OpenAPI仕様との互換性が向上します。この機能により、同じエンドポイントに対するリクエストの構造を異なる方法で示すことができ、開発者がさまざまな状況でAPIをどのように利用するかを理解しやすくなります。
リクエストボディの例は以下の理由から役立ちます：
- 開発者にリクエストのフォーマット方法を正確に示します
- 同じエンドポイントの異なるユースケースを示します
- テストを容易にするために、使用できるリクエスト構造を提供します
- ドキュメントがOpenAPI基準に従っていることを保証します
必要に応じて、すべての可能なシナリオをカバーするために無制限に追加できます。
ステップバイステップ：最初のリクエストボディの例を追加
Apidogでリクエストボディの例を追加するのは簡単です。始める方法は以下の通りです：
1. ApidogでAPIプロジェクトを開く（バージョン2.7.0以上）
2. 例を追加したいエンドポイントに移動する
3. "Edit"タブをクリックしてドキュメントエディターにアクセスし、"Request Body"セクションまでスクロールする
4. "Add Example"をクリックして新しい例を作成する
5. 例の詳細を入力する：
- 例の名前：例に明確な名前を付ける（例："Standard Request"）
- 例の値：実際のJSON、XML、または他のフォーマットデータを入力する
- 説明：この例を使用するタイミングを説明する（Markdownに対応）
- OASキー：OpenAPIエクスポート用の識別子を提供する（オプションですが推奨）
- OAS拡張：エクスポートに必要なカスタムフィールドを追加する（オプション）
6. "Save"をクリックして例を作成する
例の名前はユーザーが各例の目的を特定するのに役立ちます。空白のままにすると、Apidogは自動的に「Example 1」、「Example 2」などと名付けます。
例の値は有効なリクエスト構造を示す必要があります。JSONコンテンツタイプの場合、Apidogは有効なフォーマットを確保するのを助ける構造化エディターを提供します。
説明フィールドでは、この特定のリクエスト構造を使用するタイミングと理由について説明できます。ここでMarkdownを使用すると、説明がより明確になります。
OASキーは、ドキュメントをOpenAPI形式にエクスポートする予定がある場合に重要です。このキーは、エクスポートされた仕様内での例の識別子となります。
異なるシナリオのための複数の例の作成
最初の例を追加した後、異なるユースケースのために追加の例を作成することをお勧めします：
- 再度「+ Add」ボタンをクリックして別の例を作成する
- シナリオを明確に特定する異なる名前を付ける（例："Minimal Request"）
- この特定のシナリオの例の値を入力する
- この例を使用するタイミングを説明する詳細な説明を追加する
- 必要に応じてOASキーと拡張機能を構成する
- "Save"をクリックして例を追加する
- 関連するすべてのシナリオについてこのプロセスを繰り返す
複数の例を作成する際は、以下の一般的なシナリオをカバーすることを考慮してください：
- Standard Request：エンドポイントの一般的な使用方法
- Minimal Request：最もシンプルな有効なリクエスト構造
- Complete Request：すべての可能なフィールドを使用するリクエスト
- Special Case：特異なビジネスシナリオのための例
各例はエンドポイントの使用方法の異なる側面を示す必要があります。これにより、開発者がAPIを使用する際に可能性の広がりを理解しやすくなります。
Apidogは例を特定の順序で表示します：
- 名前が付けられた例は無名の例の前に表示されます
- OASキーが付けられた例は、それがない例の前に表示されます
- 名前またはOASキーがない例は、シリアル番号順に整理されます
最も重要な例を最初に表示させるためには、それらに明確な名前とOASキーを付けることが重要です。
テストのためのリクエストボディ例の使用
複数のリクエストボディ例の最も良い機能の一つは、それがテストを簡素化することです：
- エンドポイントの「Run」ページに移動
- リクエスト構成の「Auto-generate」セクションを見つける
- ドロップダウンメニューをクリックして、使用可能なすべての例を表示する
- テストしたい例を選択する
- 選択した例でリクエストボディが自動的に埋められる
- "Send"をクリックしてこの例でエンドポイントをテストする
これにより、異なるリクエスト構造を手動で入力または貼り付けすることなく、さまざまなシナリオを簡単にテストできます。例を迅速に切り替えて、APIがさまざまな入力をどのように処理するかを確認できます。
Apidogは、テストセッションからの例を作成することもできます：
- 「Run」ページでリクエストボディを構成する
- 「Extract」ボタンをクリックする
- 「Extract to Request Example」を選択する
- 新しい例を作成するか既存のものを更新するかを選択する
- 現在のリクエストボディが例として保存される
これは、テスト中に有効なリクエスト構造を見つけたとき、それを将来のリファレンスや文書のために保存したい場合に便利です。
例のOpenAPI互換性の確保
Apidogのリクエストボディ例は、OpenAPI仕様とシームレスに機能するように設計されています。APIドキュメントをエクスポートすると、すべての例はOAS 3.0/3.1基準に従って正しくフォーマットされます。
エクスポート中の例に対する扱いは次の通りです：
- 各例はエクスポートされた仕様に含まれます
- 例の名前は提供された場合にはOASキーから来ます（提供されていない場合にはシリアル番号）
- 例の説明はエクスポートされた形式に保持されます
- カスタムOAS拡張もエクスポートに含まれます
エクスポートされたOpenAPI仕様は、次のような構造で例を含むようになります：
"examples": { "standard_request": { "value": { "name": "John Doe", "id": "12345", "email": "john.doe@example.com" }, "summary": "Standard Request", "description": "これはすべての必須フィールドを含む標準的なリクエストです。" }, "minimal_request": { "value": { "id": "12345" }, "summary": "Minimal Request", "description": "これは必須のIDフィールドのみを含む最小限のリクエストです。" } }
OpenAPIとの互換性を確保するためには：
- すべての例に意義のあるOASキーを使用する
- 各例の目的を説明する明確な説明を提供する
- エクスポートされた仕様をレビューして、すべてが正しく表示されているか確認する
これにより、Apidog内だけでなく、OpenAPI仕様を通じて共有される際にも例が価値あるものになります。
リクエストボディ例のベストプラクティス
複数のリクエストボディ例から最大の価値を得るために、次のベストプラクティスに従ってください：
包括的な例のセットを作成する
以下をカバーする例を含めます：
- 基本的な使用法: 必要なフィールドのみ
- 典型的な使用法: よく使用されるオプションフィールドを含む
- 完全な使用法: すべての可能なフィールドを表示する
- エッジケース: 特殊な状況を示す
明確な名前を使用
- 各例にその目的を示す説明的な名称を付ける
- 異なるエンドポイント間で一貫した命名パターンを使用する
- 内容を説明しない一般的な名前（例："Example 1"）は避ける
役立つ説明を書く
- 各例を使用するタイミングと理由を説明する
- このリクエスト構造に特有の特別な考慮事項を述べる
- 説明を読みやすくするためにMarkdown形式を使用する
- 関連する場合には期待されるレスポンスを含める
論理的に例を整理する
- 最も一般的なシナリオを最初に配置する
- 関連する例をまとめる
- 混乱を避けるために古い例を削除する
- APIが変更された場合は例を更新する
OASキーを効果的に使用する
- 例の目的を説明する意味のあるキーを選択する
- API全体で一貫したキー命名を使用する
- エクスポートで問題を引き起こす可能性のある特殊文字を避ける
これらのプラクティスに従うことで、開発者がAPIを効果的に理解し使用するのを助けるリクエストボディの例を作成できます。
結論
Apidogに複数のリクエストボディの例を追加することは、APIドキュメントを改善するためのシンプルながら強力な方法です。同じエンドポイントに対するリクエストの構造を異なる方法で示すことで、開発者がさまざまな状況でAPIをどのように使用するかを理解しやすくなります。
ステップバイステップのプロセスはシンプルです：
- エンドポイントに移動し、「Edit」をクリック
- Request Bodyセクションまでスクロールして「+ Add」をクリック
- 名前、値、説明、OASキーで例を構成する
- 追加のシナリオについて繰り返す
- テストおよびドキュメントのために例を使用する
適切な例がそろっていることで、APIはより理解しやすく、テストしやすく、実装しやすくなります。これにより、採用が速くなり、サポートの質問が少なくなり、全体的な開発者体験が向上します。
今日からApidogのドキュメントに複数のリクエストボディの例を追加し、その利点を自分自身とAPIユーザーが体験してください。
