oas-validation.md

description
This page provides the technical details of the OAS Validation policy

OAS Validation

{% hint style="warning" %} This feature requires Gravitee's Enterprise Edition. For more information about Gravitee Enterpise Edition, see Gravitee APIM Enterprise Edition. {% endhint %}

Overview

The oas-validation policy validates aspects of the request and response from an upstream server definition according to the embedded OpenAPI Specification. In Gravitee, OAS files are not directly linked with the API definition, but you can use the specification as a resource in the API to define documentation and define flows and policies on the API.

You can load the load the OpenAPI specification with any of the following methods:

• Load the OpenAPI specification from YAML or JSON inserted inline with the API.
• Load it into a Content Provider Resource on the API and evolve that resource separately
• Add the OAS Validation policy when importing a v4 proxy API from an OpenAPI specification to relevant paths and flows.

{% hint style="info" %} This policy was designed to work with at least version 4.4.0 of API Management (APIM). {% endhint %}

Examples

{% hint style="warning" %} You can apply this policy to only v2 APIs and v4 HTTP proxy APIs. You cannot apply this policy to v4 message APIs or v4 TCP proxy APIs. {% endhint %}

{% tabs %} {% tab title="HTTP Proxy Configuration" %} Sample policy configuration:

"configuration": {
    "sourceUrl": "query-params-openapi.yaml",
    "validationOptions": {
       "validateRequestBody": false,
       "validateRequestParametersOptions": ["HEADERS", "COOKIES"]
    }
}

{% endtab %} {% endtabs %}

Configuration

Phases

The oas-validation policy supports the phases that are checked in the following table:

v2 Phases	Compatible?	v4 Phases	Compatible?
onRequest	true	onRequest	true
onResponse	true	onResponse	true
onRequestContent	false	onMessageRequest	false
onResponseContent	false	onMessageResponse	false

Options

You can configure the oas-validation policy with the following options:

Common options

Name	Property	Required	Description	Type	Default
OpenApi source from	sourceJson or sourceYaml or sourceUrl or resourceName	true	OpenAPI Specification in JSON or YAML format.	string	resourceName
Base path	basePath	false	Optional base path. This can be useful if e.g. your Swagger specification has been created for a public URL but you are validating requests against an internal URL where the URL paths differ.	string
Return detailed error report	validationOptions. returnDetailedErrorReport	false	Only for Bad Request (400) error. Return in the response the detailed error report. Like Schema validation errors on request/response body. This can be useful for debugging but can expose OpenApi schema details.	boolean	true
Strict operation path matching	validationOptions. strictOperationPathMatching	false	If true, a trailing slash indicates a different path than without.	boolean	true

Request Validation Options

{% hint style="info" %} None of these options are required. {% endhint %}

Name	Property	Description	Type	Default
Validate path and method exist	validationOptions. validateRequestPathAndMethod	This will validate that the path (minus the base path) and associated HTTP method matches one of the path patterns defined in the OpenApi schema.	boolean	true
Validate request content type	validationOptions. validateRequestContentType	This will validate that the request matches the requestBody.content types defined in the OpenApi schema.	boolean	true
Validate request body	validationOptions. validateRequestBody	This will validate that the request matches the request body defined in the OpenApi schema. This is only apply if the content type is application/json or application/x-www-form-urlencoded.	boolean	true
Validate request parameters (PathParams, QueryParams, Headers, Cookie)	validationOptions. validateRequestParameters	This will validate that parameters marked as required for the request exist and all request parameters match the valid values.	boolean	true
Additional options for request parameters validation	validationOptions. validateRequestParameters	Uncheck the request parameters that you don’t want to validate. (may have an impact on parameter or security validation)	enum	[QUERY_PARAMS", "HEADERS", "COOKIES"]
validationOptions. validateRequestQueryParamsUnexpected	validationOptions. validateRequestQueryParamsUnexpected	This will validate that no additional query parameters are passed that are not found in the OpenApi schema.	boolean	false
Validate request security	validationOptions. validateRequestSecurity	This will validate that the request has the required security defined in the OpenApi schema.	boolean	false

Response Validation Options

{% hint style="info" %} None of these optinos are required. {% endhint %}

Name	Property	Description	Type	Default
Validate response body	validationOptions. validateResponseBody	This will validate that the response matches the response body defined in the OpenApi schema.	boolean	true
Validate response content type	validationOptions. validateResponseContentType	This will validate that the response matches the response content type defined in the OpenApi schema.	boolean	true
Validate response status code	validationOptions. validateResponseStatusCode	This will validate that the response status code matches the response status code defined in the OpenApi schema.	boolean	true

Compatibility matrix

The following table shows the compatibility matrix for APIM and the json-validation policy:

Plugin Version	Supported APIM versions
1.x	4.4.0 and above

Errors

Phase	Code	Error key	Description
REQUEST	400 - BAD REQUEST	OAS_VALIDATION_ERROR_KEY	Request does not match the OpenAPI Specification
RESPONSE	500 - INTERNAL SERVER ERROR	NO_OAS_RESOURCE_KEY	No resource configured
REQUEST / RESPONSE	500 - INTERNAL SERVER ERROR	NO_OAS_PROVIDED_KEY	No OpenAPI Specification provided
RESPONSE	500 - INTERNAL SERVER ERROR	OAS_VALIDATION_ERROR_KEY	Response does not match the OpenAPI Specification

Changelogs

{% @github-files/github-code-block url="https://github.com/gravitee-io/gravitee-policy-oas-validation/blob/main/CHANGELOG.md" %}