Section OpenAPI Specification

Prerequisites

  • OpenAPI validation requires a license for the API Gateway feature.
  • API specification format must be in OpenAPI version 3.0command-line tool as JSON.
  •  
    Info

    Specifications in other formats or versions (e.g., Swagger 2.0) must be converted before uploading. For Swagger to OpenAPI conversions, we recommend the Mermade converter which is available as a command-line tool.

Feature scope and configuration options

After uploading the OpenAPI specification, configure and enable Enforce API validation for a mapping on the mapping detail page, Tab – API Security.

The OpenAPI filter supports the validation of requests and responses:

  • Path
  • Query parameters
  • Headers
  • Cookies
  • JSON syntax and objects

  • Body content checks are only applied to JSON documents, form-urlencoded parameters, and binary data (jpgs, gifs, ...).

 
Functional limitation

The OpenAPI feature does not support the following:

  • For requests with form-urlencoded parameters, additionalProperties can only be configured as a boolean.
  • XML and YAML content types (these are passed unchecked, even when specified in a schema).
  • Multipart requests.
  • Callback definitions.
  • OpenAPI schema in YAML format.

Behavior with unsupported OpenAPI features

Unsupported OpenAPI features are reported with a log entry and ignored, i.e., handled in a fail-open manner. The OpenAPI specification remains active, and all supported features continue to be enforced.

Errors that are reported during request processing (WR-SG-REJECT-115) include the following ones:

  • JSON parse errors
  • Structural errors in the OpenAPI document
  • Additional restrictions, such as the following ones:
    • For form-urlencoded requests, only object schemas are allowed.
    • Content-Type wildcards with syntax errors are rejected.
    • Content-Type wildcards that can never match, given the rest of the configuration, are rejected.
    • Status patterns with syntax errors are rejected (for example, 2xx is valid, while 2x1 is not).
    • Path parameters that are marked in the path but not defined in the parameter list are rejected (e.g., /path/{param}/example).
    • Path parameters that are defined in the parameter list but not marked in the path are rejected.

Logging

During request handling:

  • WR-SG-BLOCK-115-00 – Noncompliant API usage
    • constraint – provides detailed information on the violated constraint.
    • position – denotes the position in the validated request document/parameter where a constraint was violated.
  • WR-SG-REJECT-115 – OpenAPI configuration is invalid
    • The configuration could not be loaded correctly.
    • See CONF-115 entries in the log messages for investigation and error analysis.

During configuration loading:

  • SY-SG-CONF-115-00 – Config Loader: Error parsing OpenAPI specification
    • file – specifies the filename of the document containing the error.
    • position – denotes the position in the specification where the error was detected.
  • SY-SG-CONF-115-01 – Config Loader: Unsupported OpenAPI feature
    • file – specifies the filename of the document containing the unsupported feature.
    • position – denotes the position in the specification where the unsupported feature was defined.
  • SY-SG-CONF-115-02 – Config Loader: Error compiling pattern for OpenAPI string format
  • SY-SG-CONF-115-03 – Config Loader: Error compiling pattern for OpenAPI Content-Type matching

Expert settings

Expert settings control certain aspects of the OpenAPI validation:

Expert Setting Key

Description

OpenApi.StringFormat.*

Patterns for custom value formats referenced by name in specifications.

OpenApi.Authentication.*

Parameters that are explicitly allowed for authentication. Predefined entries exist for OAuth2 and OpenID Connect, but parameters for other authentication protocols can also be defined.

OpenApi.ContentType.*

List of Content-Type patterns.

Further information and links

Internal links: