# OAS Validator 配置选项

oas-validator 插件在将传入的 HTTP 请求转发到上游服务之前，根据 OpenAPI 规范进行验证。<!-- --> <!-- -->配置涵盖插件参数和插件元数据。

## 参数[​](#参数 "参数的直接链接")

有关所有插件均可使用的配置项，请参阅[插件通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md)。

* spec

  string

  ***

  包含 OpenAPI 规范的字符串。与 `spec_url` 互斥。

  内联规范受控制面 2 MB 大小限制。如果你的 OpenAPI 规范超过此限制，请改用 `spec_url` 从远程 URL 加载。

* spec\_url

  string

  ***

  用于获取 OpenAPI 规范的 URL（必须以 `http://` 或 `https://` 开头）。与 `spec` 互斥。获取的规范使用可配置的 TTL 缓存（参见插件元数据 `spec_url_ttl`），过期条目在后台异步刷新期间继续提供服务。

  自 API7 企业版 3.9.12 和 APISIX 3.17.0 起可用。

* spec\_url\_request\_headers

  object

  ***

  获取 `spec_url` 时包含的自定义 HTTP 头（例如用于认证）。

  自 API7 企业版 3.9.12 和 APISIX 3.17.0 起可用。

* ssl\_verify

  boolean

  默认值：`` APISIX 3.20.0 中为 `true`；API7 Enterprise 3.9.23 和 3.10.10 中为 `false` ``

  ***

  获取 `spec_url` 时是否验证 TLS 证书。APISIX 3.20.0 将默认值从 `false` 改为 `true`。API7 Enterprise 3.9.23 和 3.10.10 保留默认值 `false`。

  仅在明确需要兼容旧行为时将此字段设为 `false`。未经验证的连接可能使中间攻击者替换规范，并获取 `spec_url_request_headers` 中配置的凭证。

  自 API7 企业版 3.9.12 和 APISIX 3.17.0 起可用。

* timeout

  integer

  默认值：`10000`

  有效值：

  1000–60000

  ***

  获取 `spec_url` 时的 HTTP 请求超时（毫秒）。

  自 API7 企业版 3.9.12 和 APISIX 3.17.0 起可用。

* verbose\_errors

  boolean

  默认值：`false`

  ***

  如果为 true，则在验证失败时响应详细错误。

* skip\_request\_body\_validation

  boolean

  默认值：`false`

  ***

  如果为 true，则跳过请求体验证。

* skip\_request\_header\_validation

  boolean

  默认值：`false`

  ***

  如果为 true，则跳过请求头验证。

* skip\_query\_param\_validation

  boolean

  默认值：`false`

  ***

  如果为 true，则跳过查询参数验证。

* skip\_path\_params\_validation

  boolean

  默认值：`false`

  ***

  如果为 true，则跳过路径参数验证。

* reject\_if\_not\_match

  boolean

  默认值：`true`

  ***

  如果为 false，OAS 验证失败的请求仅记录错误日志，但仍会转发到上游服务。

  自 API7 企业版 3.9.6 和 APISIX 3.17.0 起可用。

* rejection\_status\_code

  integer

  默认值：`400`

  有效值：

  400–599

  ***

  请求验证失败时返回的 HTTP 状态码。例如，设置为 `422` 以区分语义验证错误（Unprocessable Entity）和格式错误的请求语法（`400` Bad Request）。仅在 `reject_if_not_match` 为 `true` 时生效。

  自 API7 企业版 3.9.8 和 APISIX 3.17.0 起可用。

* max\_req\_body\_size

  integer

  默认值：`67108864`

  有效值：

  大于或等于 1

  ***

  OpenAPI 验证时读取的请求体最大字节数。超过该大小的请求体会返回 `500 Internal Server Error`。`skip_request_body_validation` 为 `true` 时，此字段无效。自 API7 企业版 3.9.17 和 3.10.4 以及 APISIX 3.18.0 起引入。

备注

必须配置 `spec` 或 `spec_url` 之一，两者互斥。

## 插件元数据[​](#插件元数据 "插件元数据的直接链接")

* spec\_url\_ttl

  integer

  默认值：`3600`

  ***

  从 `spec_url` 获取的规范缓存的 TTL（秒）。过期后，过期条目在后台异步刷新时继续提供服务。

  自 API7 企业版 3.9.12 和 APISIX 3.17.0 起可用。

  在 `spec_url_ttl` 秒内未被任何请求使用的规范会从内存中释放。此空闲缓存清理由 APISIX 3.20.0、API7 Enterprise 3.9.22 和 3.10.9 支持。
