Skip to content
CA API Gateway - 9.3
Documentation powered by DocOps

Validate Against Swagger Document Assertion

Last update June 14, 2018

The Validate Against Swagger Document Assertion validates a request against the API from a Swagger document. You can check the following:

  • The request's scheme is allowed by the API
  • The request's path is valid
  • The request's method is allowed by the API
  • The security credentials required by the API are present in the request

Prerequisite: 

  • The Swagger document must be available from a context variable before this assertion is encountered in the policy.
  • The Swagger document is in the application/json format.

Contents:

Context Variables

This assertion populates the following variables with information about the API:

Variable Description
<prefix>.host

Returns the String value of the original host (name or IP) serving the API from the Swagger document, optionally including the port.

Example: pestore.swagger.io

<prefix>.baseUri

Returns the base path on which the API is served, which is relative to the host, from the Swagger document. The value begins with a leading forward slash (/).

Example: /v2

<prefix>.apiUri

Returns the API path from the request.

Example: For the URL http://gatewayurl:8080/swaggerService/pet/1/uploadImage, the apiUri is "/pet/1/uploadImage".

<prefix>.path

(available as of v9.3 CR3)

Returns the path in the Swagger document against which the request was validated. For example, if the request is:

http://machine.mycompany.com:8081/swagger/pet/2002/uploadimage

The Gateway returns this path:

sw.path: /pet/{petId}/uploadImage

Cluster Properties

None

Properties

Setting What you should know...
Swagger Document Enter the context variable containing the Swagger document to use for parsing the request.
Service Base

Optionally specify the service URI used to identify the service. 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.

Validation Options

Choose how to validate the request:

    • Validate Path: Validate the path portion of the request, excluding the base path and service URI, against the API from the Swagger document. If not selected, then any path is accepted. This validation is enabled by default. Tip: Disabling path validation also disables all the other validation options.
    • Validate Method: Check whether the method from the request is allowed to be used with the API from the Swagger document. If not selected, then any method is accepted. Tip: Method validation is available only when Path validation is chosen.
    • Validate Scheme: Check whether the scheme from the request (http or https) is allowed for the API from the Swagger document. If not selected, any scheme (including a blank scheme) is accepted. Tip: Scheme validation is available only when Method validation is chosen.
    • Require Security Credentials to be Present: Check whether the appropriate security credentials specified in the API from the Swagger document are present in the request. If not selected, then any credentials (or no credentials) are accepted. Tip: Security credentials can be checked only when Method validation is chosen.

      Note: This assertion does not collect or authenticate security credentials. It only verifies that they are present. If no permitted credentials are found, then the assertion fails.


Variable Prefix Enter a prefix to add to the context variables created by this assertion. The default prefix is "sw".

Example Policy

The following template policy is created when you run the Publish Swagger Service Wizard. It shows how the Validate Against Swagger Document Assertion can be used in a policy. 

The example policy retrieves the Swagger 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 Swagger document is retrieved from the URL specified in ${serviceSwaggerURL} context variable.

Frequently Asked Questions

Question Answer
Why is my service not resolvable? The service URI in the service properties 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 -> Scheme -> Security credential presence. The validation stops whTen one of the validations fails.
What happens when path validation fails? Audit code 11401 is logged and the assertion fails.
What happens if an operation cannot be found for the request method and path? Audit code 11402 is logged and the assertion fails.
What happens if a request scheme cannot be found for a valid path, method, and operation? Audit code 11403 is logged and the assertion fails.
What happens if the Swagger document cannot be extracted from the context variable? Audit code 11400 is logged and the assertion fails.
What happens if the Swagger document is poorly formed or cannot be parsed? Audit code 11400 is logged and the assertion fails.
What happens if the security credentials are missing? If the security credentials are missing or invalid and the validation is enabled, audit code 11406 is logged and the assertion fails.
What happens if the security scheme from the Path is not defined in the Swagger document? Audit code 11407 is logged and the assertion fails.
How can I make the cached Swagger document live longer? Modify the Look Up in Cache Assertion or Store to Cache Assertion in the sample policy.

available beginning with 9.2 CR8 Hotfix 1

Was this helpful?

Please log in to post comments.