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 を参照しています。
