OAS Validator Configuration
Configuration reference for the OAS Validator plugin (`oas-validator`): the parameters and plugin metadata, each attribute with its type, whether it is required, its default and its accepted values.
Parameters
See plugin common configurations (opens in Apache APISIX docs) for configuration options available to all plugins.
spec — string · optional · since APISIX 3.17.0 · API7 Gateway 3.2.5.0
String containing the OpenAPI spec. Mutually exclusive with spec_url.
The inline spec has a 2 MB size limit imposed by the control plane. If your OpenAPI specification exceeds this limit, use spec_url instead to load the spec from a remote URL.
spec_url — string · optional · since APISIX 3.17.0 · API7 Gateway 3.9.12
URL to fetch the OpenAPI spec from (must start with http:// or https://). Mutually exclusive with spec. The fetched spec is cached with a configurable TTL (see plugin metadata spec_url_ttl), and stale entries continue serving requests while the spec refreshes in the background.
Available in API7 Enterprise from version 3.9.12 and APISIX from version 3.17.0.
spec_url_request_headers — object · optional · since APISIX 3.17.0 · API7 Gateway 3.9.12
Custom HTTP headers to include when fetching spec_url (e.g. for authentication).
Available in API7 Enterprise from version 3.9.12 and APISIX from version 3.17.0.
ssl_verify — boolean · optional · default: false · since APISIX 3.17.0 · API7 Gateway 3.9.12
Whether to verify the SSL certificate when fetching spec_url.
Available in API7 Enterprise from version 3.9.12 and APISIX from version 3.17.0.
timeout — integer · optional · default: 10000 · since APISIX 3.17.0 · API7 Gateway 3.9.12
Valid values: 1000–60000
HTTP request timeout in milliseconds when fetching spec_url.
Available in API7 Enterprise from version 3.9.12 and APISIX from version 3.17.0.
verbose_errors — boolean · optional · default: false · since APISIX 3.17.0 · API7 Gateway 3.2.5.0
If true, respond with detailed error if the validation fails.
skip_request_body_validation — boolean · optional · default: false · since APISIX 3.17.0 · API7 Gateway 3.2.5.0
If true, skip the validation of request body.
skip_request_header_validation — boolean · optional · default: false · since APISIX 3.17.0 · API7 Gateway 3.2.5.0
If true, skip the validation of request header.
skip_query_param_validation — boolean · optional · default: false · since APISIX 3.17.0 · API7 Gateway 3.2.5.0
If true, skip the validation of query parameters.
skip_path_params_validation — boolean · optional · default: false · since APISIX 3.17.0 · API7 Gateway 3.2.5.0
If true, skip the validation of path parameters.
reject_if_not_match — boolean · optional · default: true · since APISIX 3.17.0 · API7 Gateway 3.9.6
If false, requests that fail OAS validation are logged as error but the request is still forwarded to the upstream service.
Available in API7 Enterprise from 3.9.6 and APISIX from version 3.17.0.
rejection_status_code — integer · optional · default: 400 · since APISIX 3.17.0 · API7 Gateway 3.9.8
Valid values: 400–599
HTTP status code to return when request validation fails. For example, set to 422 to distinguish semantic validation errors (Unprocessable Entity) from malformed request syntax (400 Bad Request). Only effective when reject_if_not_match is true.
Available in API7 Enterprise from version 3.9.8 and APISIX from version 3.17.0.
max_req_body_size — integer · optional · default: 67108864 · since APISIX 3.18.0 · API7 Gateway 3.9.17
Valid values: greater than or equal to 1
Maximum request body size in bytes read for OpenAPI validation. A larger body returns 500 Internal Server Error. This field has no effect when skip_request_body_validation is true. Introduced in API7 Enterprise 3.9.17 and 3.10.4, and APISIX 3.18.0.
One of spec or spec_url must be configured. They are mutually exclusive.
Plugin Metadata
spec_url_ttl — integer · optional · default: 3600 · since APISIX 3.17.0 · API7 Gateway 3.9.12
TTL in seconds for cached specs fetched from spec_url. After expiry, stale entries continue serving requests while the spec refreshes asynchronously in the background.
Available in API7 Enterprise from version 3.9.12 and APISIX from version 3.17.0.