CA API Gateway 9.1

PDF
index 10.1 congw.10.1 10.0 congw.10.0 9.4 9.3 9.2 9.1 9.0
English

Validate Against Swagger Document Assertion

The Validate Against Swagger Document Assertion validates a request against the API from a Swagger document. You can check the following:
gateway91
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".
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.
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.
      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. 
Sample_Swagger_policy.png
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.