メインコンテンツまでスキップ

APIの設計と作成

APIの設計と作成には、APIドキュメントの仕様（APIパス、パラメータ、戻り値、データ構造など）を定義する必要があります。

ご案内：

Postmanとは対照的に、ApidogはAPIの設計と実行のアイデアの区別をします。

  • APIの設計：新しいAPIページとAPI 詳細設定ページは、APIを実行するためではなく、APIドキュメントを定義するために設計されています。したがって、これらのページはパラメータの値を設定するのではなく、APIの基本情報（パラメータ名やパラメータの説明など）を定義するためにのみ使用できます。パラメータ値、前処理Script、後処理Scriptなどを、APIの実行ページで設定してください。
  • APIの実行：API 実行ページ（API 詳細設定ページからアクセス可能）は一時的なデバッグのために設計されています。実行後、パラメータ、前処理Script、後処理Scriptなどを保存するには、「ケースとして保存」をクリックしてください。そうしない場合、タブを閉じた後に情報がなくなります。
共通問題

  • PostmanのようにAPIを事前設計せずに素早くデバッグする方法はありますか？ クイックRequest 機能を利用します。

  • 新しいAPIを開くときに、タブが上書きされることを防止するにはどうすればいいですか？ タブをダブルクリックするか、ツリーメニューで当該項目をダブルクリックしてください。これはVSCodeと同じような操作です。タブの内容に変更があれば、タブが自動的に修正されます。

クイックスタート​

  1. 左側の検索ボックスの近くにある + ボタンをクリックして、新しいウィンドウを開くか、ショートカットキーの「Ctrl(⌘) + N」を押します。

apidog

  1. 新しいウィンドウでAPI 関連の情報を入力します。

apidog

APIのパス​

APIのパスは、先頭がスラッシュ（/）で始まります。例えば： /pets、 /pets/{id}

apidog

ご案内：
  1. APIパスにはHTTPプロトコルとドメイン名を含めないことをお勧めします。これは、環境管理のセクションでプリフィックスURLを設定できます。設定したプリフィックスURLは、デバッグ中にURLの先頭に自動的に追加されます。
  2. システムはHTTPプロトコルとドメイン名がAPIパスに含まれていることに対応できますが、お勧めしません。デバッグ中に、システムがURLに「http://」と「https://」が含まれることを検出した場合、現在利用中の環境中のプリフィックス URLが自動的に無視されます。
  3. Apidogでは、Pathパラメータはコロン（例：/pets/:id）の代わりに、波括弧（例：/pets/{id}）で囲まれています。
  4. APIパスにはQueryパラメータ（URLの「?」以降のパラメータ）を含めることはできません。Queryパラメータは、下記のRequestパラメータのセクションに入力する必要があります。

Requestパラメータ​

Params​

Paramsにqueryとpathパラメータが含まれています。

  • Queryパラメータ：URLの「?」以降のパラメータです。
  • Pathパラメータ：波括弧内のPathパラメータを自動的に抽出します。例えば： たとえば、Apidogは /pets/{id} のパスパラメータとして {id} を抽出します。

apidog

Bodyパラメータ​

apidog

Bodyパラメータのタイプ​

  • none: bodyパラメータがありません。
  • form-data: Content-typeがmultipart/form-dataです。
  • x-www-form-urlencoded: Content-typeがapplication/x-www-form-urlencodedです。
  • json: Content-Typeがapplication/jsonです。
  • xml: Content-Typeがapplication/xmlです。
  • binary: ファイルベースのデータを送信します。
  • raw: そのほかのテキストベースのデータを送信します。
ご案内：

  • bodyパラメータがGET Requestでのみ設定できます。

  • body parameterのタイプがjsonかxmlの場合、データ構造を設定する必要があります。そのデータ構造はSchimaを参照できます。 詳細のドキュメントを見る。

ご案内：

  • Bodyパラメータのタイプに基づいて自動的にRequestのHeaderに追加されるので、API requestを送信する場合、Content-Typeを手動で設定する必要がありません。

  • 手動でHeaderのContent-Typeを設定する必要がある場合、その値がBodyパラメータに合わせる必要があります。そうでなければ、システムが手動入力されたContent-Typeを自動的に無視します。

    • Bodyパラメータがform-dataの場合、 Content-Typeをmultipart/form-dataか、charset=GBKに設定できます。ただし、Content-Typeがapplication/jsonに設定する場合、パラメータタイプと一致しないため、システムはそれを無視します。

  • Bodyパラメータがrawの場合、Content-Typeの値の手動設定に制限がありません。

パラメータで環境変数・グローバル変数・ローカル変数の使用​

v-pre

すべてのパラメータに変数を使用できます。二重波括弧を使用して変数名を囲むことで変数を参照します。たとえば、{{my_variable}}は、my_variableという名前の変数を参照することを意味します。

変数以外、パラメータ値を文字列にすることもできます。たとえば、パラメータを prefix-{{my_variable}}-surfix として設定できます。実行時、パラメータ値は prefix-123-surfix になります。

変数の詳細については、ドキュメントを参照してください。

Response​

返されたResponseには、次の部分があります：

  • APIから返されたHTTPステータスコード
  • 返されるコンテンツのデータ形式：JSON,XML,HTML,Raw,Binary
  • データ構造：データ構造を設定できるのはJSONとXMLのみです。データ構造の詳細については、こちらをご覧ください。
ご案内：

  • APIが異なる状況で異なるデータ構造を返す場合、複数のResponseを設定できます。Responseを追加するには、Return Responseモジュールの右上にある[+ 追加]をクリックします。

  • データ構造を定義した後、APIをデバッグするときに、システムは返されたデータが定義されたデータ構造に準拠しているかどうかを自動的に確認します。ここでAPIのデバッグ/APIのユースケースの詳細を見る。

  • データ構造を定義した後、Mockを使用する場合、システムはカスタマイズされたデータ構造に基づいて現実的なデータをMockします。ここでMockデータの詳細を見る。

共通 Response​

共通 Responseは、返されたResponseを再利用するように設計されています。

時々、異なるAPIは同じデータ構造を返すことがあります。例えば、リソースが存在しない（404）、アクセス権限がない（401）など。重複操作を避けて、より効率的に管理するため、これらを共通 Responseに設定することをお勧めします。

共通 Responseとして保存：プロジェクトの設定を開く->共通 Responseを選択すると、ここで共通 Responseを管理できます。

apidog

Responseの例​

Responseのデータ例を設定することで、APIドキュメントを確認する人がデータ構造をすばやく理解できます。

Responseのデータ例は、Responseモジュールの右上にある「+ 追加」をクリックして複数回設定することができます。成功例と失敗例という、少なくとも2つの例を設定することをお勧めします。

そのほか​

OperationID​

OperationIdプロパティの設定をサポートします。OpenAPI 形式でエクスポートすると、この値はOperationオブジェクトのOperationIdにエクスポートされます。

apidog