Swagger は、アプリケーションのドキュメントを自動的に構成する特別なツールです。 RESTful API は、アプリケーションのドキュメントを自動的に構成する特別なツールです。
その利点は、アプリケーションのすべてのエンドポイントに目を通すだけでなく、リクエストを送信してレスポンスを受信することで、それらの動作をすぐにテストすることができる点にあります。
にアクセスするには Swagger にアクセスするには、公開アプリケーションの Preview ボタンをクリックし、必要な出版計画の名前( Deploy Plan).
新しく開いたウィンドウに、利用可能なエンドポイントおよびこれらのエンドポイントに関連付けられたメソッドのリストが表示されます。一部のリクエストは、許可されたユーザーの特定のグループのみが利用できます ( Middleware の Auth module の各リクエストを参照してください。 Endpoints セクションを参照してください)。A Bearer Token は許可されたユーザーのみに許可されているリクエストに必要です。
で対応するエンドポイントに直接アクセスして、このトークンを取得することができます。 Swagger に直接アクセスして、このトークンを取得することができます ( Auth セクションを参照してください。 POST /auth リクエスト)。
を押し Try it out を押し、ログイン名とパスワードを入力すると、トークンを取得できます。
リクエストは Execute.正常に送信された場合は token フィールドに Bearer token の値が表示されます。
認可ユーザトークンを取得する第二の方法は、デプロイされたアプリケーションのリクエストボディの中にトークンを見つけることです。
- ウェブブラウザで F12 キーを押して、開発者用ツールを開いてください。
- デプロイされたアプリケーションで、任意のリクエストを送信してください（たとえば、テーブルの更新など）。このリクエストを送信するユーザーは、このエンドポイントへのアクセスが許可されている必要があります。
- を開き Network タブを開き、該当するリクエストを探します。
- に移動します。 Headers タブを開き Request Headers セクションに移動します。 Bearer token の下に表示されます。 Authorization.
提供する Bearer token を入力します。 Swagger を押して Authorize を押して、前のステップでコピーした値を貼り付けます。
テスト要求の場合は、目的のグループと実行したい方法を選択します。を押して、リクエストの入力パラメータを入力します。 Try it out をクリックし、リクエストの入力パラメータを入力します。をクリックします。 Execute をクリックすると、応答が実行されます。
リクエストがサーバーによって正しく処理された場合、最も期待されるレスポンスはコード 200 で、レスポンス構造がどのように見えるかを示しています。
-
401 - 必要な認証トークンがないか、無効なため、リクエストは正常に完了しませんでした。
-
404 - リクエストは正常に処理されましたが、要求されたリソースが見つかりませんでした。
-
422 - リクエストの入力に不正なパラメーターが渡されました。
-
500 - サーバーによる要求の処理エラーです。
カスタム エラーを発生させる
カスタムBPと関連するリクエストでは、BPエディタの Raise Error ブロックを使って、説明付きのカスタムエラーコードを作成することができます。そのような処理の例を以下に示します。
この場合、上記のBPに関連するエンドポイントへのリクエストに失敗すると、サーバーは DB: Create Candidate block.この例でのエラーコードは、ユーザーが指定したものであれば何でもよい。
注:HTTP 418 I'm a teapot client エラー応答コードは、サーバーが永久にティーポットであるため、コーヒーを淹れることを拒否していることを表します。一時的にコーヒーが切れているコーヒー/ティーポットの組み合わせは、代わりに503を返すべきです。このエラーは、1998年と2014年のエイプリルフールのジョークで定義されたHyper Text Coffee Pot Control Protocol を参照しています。
