Validate Against OpenAPI Document Assertion

The Validate Against OpenAPI Document Assertion validates a request against the API from an OpenAPI document. You can configure the assertion properties to select specific portions of the request for validation. This assertion supports only OpenAPI 3.0 specification.
9-5
The
Validate Against OpenAPI Document Assertion
validates a request against the API from an OpenAPI document. You can configure the assertion properties to select specific portions of the request for validation. This assertion supports only OpenAPI 3.0 specification.
You can check the following:
  • The request's path is valid.
  • The request's method is allowed by the API.
  • The request body content against the JSON schema if request body is of type JSON.
  • The security credentials required by the API are present in the request.
Prerequisite:
  • OpenAPI document must be available from a context variable before this assertion is encountered in the policy.
  • OpenAPI document can be a JSON or YAML document.
Contents:
Using the Assertion
To add an assertion, refer to Adding an Assertion for instructions on adding this assertion from
Message Validation/Transformation Assertions
under
Policy Assertions
.
  1. Right-click
    Validate Against OpenAPI Document
    in the policy window and then select
    Validate Against OpenAPI Document Properties
    or double-click the assertion in the policy window.
    The assertion properties are displayed.
  2. Enter the context variable containing the
    OpenAPI Document
    to use for validating the request.
  3. (Optional) Specify the service URI used to identify the service in the
    Service Base
    field. You may reference context variables. If not specified, the current service URI is used.
    Note:
    The service URI must end with '
    /*
    ' (excluding the quotes) for it to be resolvable by this assertion.
  4. Choose how to validate the request using the following options:
    1. Validate Path:
      Validate the path portion of the request, excluding the server URL and service URI, against the API from the OpenAPI document. This validation is selected by default. If this checkbox is cleared, then any path is accepted.
      Note:
      Disabling path validation also disables all the other validation options.
    2. Validate Method
      : Check whether the method from the request is allowed to be used with the API from the OpenAPI document. This validation is selected by default. If this checkbox is cleared, then any method is accepted.
      Note:
      Method validation is available only when Path validation is selected.
    3. Validate Body:
      Check to validate the request body content against the JSON schema from the OpenAPI document if request body is of type JSON. Request body validation has the same limitation as that of Validate JSON Schema, if any.
      • JSON schema is cached after first load.
      • You can configure cache size and eviction time in Gateway System Properties.
      • If the request body length is more than the value that is configured in the system property, Gateway System Properties, it is ignored for request body validation.
      Note:
      Request body validation is available only when Method validation is selected.
    4. Require Security Credentials to be Present
      : Check whether the appropriate security credentials specified in the API from the OpenAPI document are present in the request. This validation is selected by default. If this checkbox is cleared, then any credentials (or no credentials) are accepted.
      Note:
      • Security credentials validation can be checked only when Method validation is chosen.
      • This assertion does not collect or authenticate security credentials. It only verifies that the credentials are present. If no permitted credentials are found, then the assertion fails.
  5. Change the prefix value to add to the context variables created by this assertion in the
    Variable Prefix
    field, if needed. The default prefix value is
    openapi
    .
  6. Click
    OK
    .
Context Variables
If the validation is successful, this assertion populates the following variables with information about the API.
If validation fails, the assertion falsifies. In this case, if the OpenAPI document was parsed successfully, the assertion populates
<prefix>
.servers
and
<prefix>
.expandedPath
context variables.
Variable
Description
<prefix>
.servers
Returns a multivalued context variable, which contains one or more server URLs that are defined in the OpenAPI document.
Example: http://petstore.swagger.io/api
You can retrieve individual URL using index values. For example,
${<prefix>.servers[2]}
.
<prefix>
.path
Returns the path in the OpenAPI document against which the request was validated. For example, if the request is:
http://machine.mycompany.com:8081/openapi/pets/12345
The Gateway returns this path:
openapi.path: /pets/{petId}
<prefix>
.
expandedPath
Returns the expanded path in the OpenAPI document against which the request was validated.
Example:
/pets/12345
Cluster Property
Property
Description
openapi.maxDownloadSize
Specifies the maximum size in bytes of an OpenAPI specification document to download. Enter
0
for unlimited size (Integer).
Default:
10485760
openapi.modelCache.maxSize
Specifies the maximum entries in a cache.
Default:
100
openapi.modelCache.idleTimeout
Specifies the timeout in milliseconds to remove an unused entry from the openAPI model cache.
Default:
300000 (5 minutes)
Example Policy
The following template policy is created when you run the Publish OpenAPI Service Wizard. It shows how the Validate Against OpenAPI Document Assertion can be used in a policy.
policy template.png
The example policy retrieves the OpenAPI document from a specified URL and then caches it for the period of time specified in the Store to Cache Assertion. When the cache expires, the OpenAPI document is retrieved from the URL specified in
${openapi.docUrl}
context variable.
Frequently Asked Questions
Question
Answer
Why is my service not resolvable?
The service URI in the service properties of the Web Service must end with '
/*
' for it to be resolvable by this assertion.
What is the validation order if all validation options are enabled?
The order is: Path -> Method -> Security credential presence
and Request Body
. The validation stops when one of the validations fails.
How can I make the cached OpenAPI document live longer?
Modify the Store to Cache Assertion in the sample policy.