OAS Validator Configuration

Parameters

See plugin common configurations for configuration options available to all plugins.

• spec — string · optional

  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

  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

  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

  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

  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

  If true, respond with detailed error if the validation fails.

• skip_request_body_validation — boolean · optional · default: false

  If true, skip the validation of request body.

• skip_request_header_validation — boolean · optional · default: false

  If true, skip the validation of request header.

• skip_query_param_validation — boolean · optional · default: false

  If true, skip the validation of query parameters.

• skip_path_params_validation — boolean · optional · default: false

  If true, skip the validation of path parameters.

• reject_if_not_match — boolean · optional · default: true

  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

  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

  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.

Plugin Metadata

• spec_url_ttl — integer · optional · default: 3600

  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.