The OpenAPI Validator Filter validates requests against a configured OpenAPI Document.

The OpenAPI document describes an API, detailing how to make requests and what form the responses will take. If a request fails validation against the OpenAPI document, this filter will reject the request. For example, if the OpenAPI document requires a query parameter for a particular operation and the request for that operation is missing the query parameter, this filter will discontinue processing of the request and send an error response.

General filter information

  • Name: openapi-validator

  • Default Configuration: openapi-validator.cfg.xml

  • Released: 9.0.1.0

  • Bundle: repose-filter-bundle

  • Schema

Prerequisites & Postconditions

Required Request Headers

Vary based on configuration.

This filter itself does not require any request headers, however the configured OpenAPI document may.

Required Preceding Filters

This filter has no dependency on any other filter.

Request Headers Created

This filter does not create/modify any request headers.

Request Body Changes

This filter does not modify the request body.

This filter is not a dependency of any other filter.

Response Body Changes

This filter does not modify the response body.

Response Headers Created

This filter does not create/modify any response headers.

Response Status Codes

Table 1. Status Codes
Status Code Reasons

400

  • The OpenAPI document does not specify a request body, but the request contains a body.

  • The OpenAPI document requires a request body, but the request does not contain a body.

  • The OpenAPI document specifies a security scheme, but the request does not contain data required by that scheme.

  • The OpenAPI document specifies a security scheme, but the request does not meet the requirements of that scheme.

  • The OpenAPI document requires a request header, but the request does not contain that header.

  • The OpenAPI document requires a query parameter, but the request does not contain that query parameter.

  • The OpenAPI document requires a parameter, but the request does not contain that parameter.

  • The OpenAPI document requires a parameter with a value from an enumerated set, but the parameter value from the request does not exist in the set.

  • The OpenAPI document requires a single parameter value, but the request contains multiple parameter values.

  • The OpenAPI document requires a maximum number of parameter values, but the request parameter contains more values than that number.

  • The OpenAPI document requires a minimum number of parameter values, but the request parameter contains fewer values than that number.

  • The OpenAPI document requires a parameter with only unique values, but the request parameter contains duplicate values.

  • The request contains a Content-Type header with an invalid value.

  • The request contains an Accept header with an invalid value.

  • The OpenAPI document requires JSON content, but the request contains invalid JSON content.

  • A validation failure that is not explicitly expected has occurred.

404

  • The OpenAPI document does not contain a path matching the path of the request.

405

  • The OpenAPI document does not contain an operation matching the method of the request.

406

  • The OpenAPI document does not contain a response content mapping for the media type(s) specified by the Accept header of the request.

415

  • The OpenAPI document does not contain a request content mapping for the media type(s) specified by the Content-Type header of the request.

500

  • An error occurs while attempting to read the request.

  • An unexpected error occurs while this filter is processing.

  • An unknown error occurs while validating schema from the OpenAPI document against the request.

Examples

OpenAPI Request Validation

This configuration will validate inbound requests against an OpenAPI document.

openapi-validator.cfg.xml
<openapi-validator xmlns="http://docs.openrepose.org/repose/openapivalidator/v1.0"
                   href="https://raw.githubusercontent.com/OAI/OpenAPI-Specification/3.0.2/examples/v3.0/petstore.yaml"/> (1)
1 A URL which specifies where the OpenAPI document to use for validation is located and how to access it.
This reference can be either local or remote, absolute or relative.
If relative, this reference will be resolved as a file in the Repose configuration root directory.
Scheme (e.g., http:, file:) support is determined by the JVM running this filter.

Additional Information

This filter is backed by the Swagger Request Validator library. As such, the validations supported by this filter are exactly those supported by that library.

Validation Failure Priority

If a request fails validation due to more than one issue, the issue with the highest priority will be used to set the response status code and reason.

The following list provides all request validation issues handled by this filter in priority order (i.e., issues higher on the list will be used over issues lower on the list):

  1. Path missing

  2. Method not allowed

  3. Unexpected body

  4. Missing body

  5. Missing security

  6. Invalid security

  7. Missing header

  8. Missing query

  9. Missing parameter

  10. Invalid enum parameter

  11. Invalid parameter collection

  12. Invalid parameter collection format

  13. Parameter collection contains too many items

  14. Parameter collection contains too few items

  15. Parameter collection contains duplicate items

  16. Invalid content type

  17. Content type not allowed

  18. Invalid accept type

  19. Accept type not allowed

  20. Invalid JSON content

  21. Unknown schema validation problem

  22. Any other validation failure