Validate Against OpenAPI Document アサーション

Validate Against OpenAPI Document アサーションでは、OpenAPI ドキュメントの API に対してリクエストを検証します。検証でリクエストの特定の部分を選択するようにアサーション プロパティを設定できます。このアサーションでは、OpenAPI 3.0 仕様のみをサポートしています。
9-5
Validate Against OpenAPI Document アサーション
では、OpenAPI ドキュメントの API に対してリクエストを検証します。検証でリクエストの特定の部分を選択するようにアサーション プロパティを設定できます。このアサーションでは、OpenAPI 3.0 仕様のみをサポートしています。
以下を確認できます。
  • リクエストのパスが有効
  • リクエストのメソッドが API で許可されている
  • リクエスト本文が JSON タイプの場合、リクエスト本文の内容が JSON スキーマに適合している
  • API で必要なセキュリティ認証情報がリクエスト内に存在する
前提条件
  • OpenAPI ドキュメントは、このアサーションがポリシーに出現する前に、コンテキスト変数から利用可能である必要があります。
  • OpenAPI ドキュメントは、JSON または YAML 形式にすることができます。 
目次
 
 
アサーションの使用
アサーションを追加するには、「アサーションの追加」を参照して、このアサーションを
[Policy Assertions]
[Message Validation/Transformation Assertions]
から追加する手順に従います。
  1. ポリシー ウィンドウで
    [Validate Against OpenAPI Document]
    を右クリックして
    [Validate Against OpenAPI Document Properties]
    を選択するか、ポリシー ウィンドウでアサーションをダブルクリックします。
    このアサーションのプロパティが表示されます。
  2. リクエストの検証に使用する
    OpenAPI ドキュメント
    を含むコンテキスト変数を入力します。
  3. (オプション)
    [Service Base]
    フィールドで、サービスの識別に使用されるサービス URI を指定します。コンテキスト変数を参照することもできます。指定されていない場合は、現在のサービス URI が使用されます。
    注:
    サービス URI がこのアサーションによって解決されるには、この URI は '
    /*
    ' で終わる必要があります(引用符を除く)。
  4. 以下のオプションを使用して、リクエストを検証する方法を選択します。
    1. Validate Path:
      サーバ URL およびサービス URI を除く、リクエストのパス部分を OpenAPI ドキュメントの API に対して検証します。この検証は、デフォルトで選択されています。このチェックボックスをオフにすると、任意のパスが受け入れられます。
      注:
      パスの検証を無効にすると、その他すべての検証オプションも無効になります。
    2. Validate Method
      : リクエストのメソッドが、OpenAPI ドキュメントの API での使用が許可されているかどうかを確認します。この検証は、デフォルトで選択されています。このチェックボックスをオフにすると、任意のメソッドが受け入れられます。
      注:
      メソッドの検証は、パスの検証が選択されている場合のみ使用できます。
    3. Validate Body:
      リクエスト本文が JSON タイプの場合、OpenAPI ドキュメントの JSON スキーマに対してリクエスト本文の内容を検証します。リクエスト本文の検証には、JSON スキーマの検証と同じ制限があります(ある場合)。
      • JSON スキーマは、最初のロード後にキャッシュされます。
      • Gateway システム プロパティでキャッシュ サイズと削除時間を設定できます。
      • リクエスト本文の長さは、Gateway システム プロパティに設定されている値を超えている場合、リクエスト本文の検証では無視されます。
         
      注:
      リクエスト本文の検証は、メソッドの検証が選択されている場合にのみ使用できます。
    4. Require Security Credentials to be Present
      : OpenAPI ドキュメントの API で指定された適切なセキュリティ認証情報が、リクエスト内に存在するかどうかを確認します。この検証は、デフォルトで選択されています。このチェックボックスがオフの場合、任意の認証情報(または認証情報なし)が受け入れられます。
      注:
      • セキュリティ認証情報の検証は、メソッドの検証が選択されている場合にのみ使用できます。 
      • このアサーションでは、セキュリティ認証情報を収集または認証しません。認証情報の有無のみを確認します。許可されている認証情報が見つからない場合は、アサーションが失敗します。
  5. 必要に応じて、このアサーションによって作成されたコンテキスト変数に追加するプレフィックス値を
    [Variable Prefix]
    フィールドで変更します。デフォルトのプレフィクス値は
    openapi
    です。 
  6. [OK]
    をクリックします。
コンテキスト変数
検証が成功した場合、このアサーションは、API に関する情報を以下の変数に入力します。 
検証が失敗した場合、アサーションは失敗します。この場合、OpenAPI ドキュメントが正常に解析された場合、アサーションによって
<prefix>
.servers
および
<prefix>
.expandedPath
コンテキスト変数に値が入力されます。
変数
説明
<prefix>
.servers
複数値のコンテキスト変数を返します。この変数には、OpenAPI ドキュメントで定義されている 1 つ以上のサーバ URL が含まれています。
例: http://petstore.swagger.io/api
インデックス値を使用して、個々の URL を取得できます。たとえば、
${<prefix>.servers[2]}
などです。
<prefix>
.path
リクエストの検証に使用された OpenAPI ドキュメント内のパスを返します。たとえば、以下のようなリクエストが発生したとします。
http://machine.mycompany.com:8081/openapi/pets/12345
この場合、Gateway は以下のパスを返します。
openapi.path: /pets/{petId}
<prefix>
.
expandedPath
リクエストの検証に使用された OpenAPI ドキュメント内の展開されたパスを返します。 
例:
/pets/12345
クラスタ プロパティ
プロパティ
説明
openapi.maxDownloadSize
ダウンロードする OpenAPI 仕様ドキュメントの最大サイズをバイト単位で指定します。
0
を入力すると、サイズは無制限(整数)になります。
デフォルト:
10485760
ポリシーの例
Publish OpenAPI Service ウィザードを実行すると、以下のテンプレート ポリシーが作成されます。テンプレート ポリシーは、Validate Against OpenAPI Document アサーションをポリシーでどのように使用できるかを示します。 
 policy template.png 
このポリシーの例では、指定された URL から OpenAPI ドキュメントを取得して、Store to Cache アサーションで指定した時間、そのドキュメントをキャッシュします。キャッシュが期限切れになると、OpenAPI ドキュメントは、
${openapi.docUrl}
コンテキスト変数で指定された URL から取得されます。
よくある質問
質問
回答
サービスを解決できないのはなぜですか。
Web サービスのサービス プロパティのサービス URI がこのアサーションで解決可能となるには、この URI は「
/*
」で終わる必要があります。
すべての検証オプションを有効にした場合、検証の順序はどうなりますか。
次の順序になります: パス -> メソッド -> セキュリティ認証情報の有無
およびリクエスト本文
。検証のいずれかが失敗した場合、検証が停止します。
 
キャッシュされた OpenAPI ドキュメントの有効期間を延長することはできますか。
サンプル ポリシー内の Store to Cache アサーションを変更します。