Skip to main content
Version: 3.17

oas-validator

描述#

oas-validator 插件在请求转发至上游服务之前，根据 OpenAPI Specification（OAS）3.x 文档对入站 HTTP 请求进行校验。可校验内容包括请求方法、路径、查询参数、请求头以及请求体。

OpenAPI 规范可以以内联 JSON 字符串的形式提供，也可以从远程 URL 获取并配置缓存。校验失败时返回可配置的 HTTP 错误状态码，并可选择在响应体中包含详细的错误信息。

属性#

名称类型必选项默认值有效值描述
specstring否*内联 OpenAPI 3.x 规范（JSON 格式）。未设置 spec_url 时必填。
spec_urlstring否*^https?://获取 OpenAPI 规范的 URL。未设置 spec 时必填。
spec_url_request_headersobject否获取 spec_url 时附带的自定义 HTTP 请求头，适用于需要鉴权的规范接口。
ssl_verifyboolean否false获取 spec_url 时是否校验 TLS 证书。
timeoutinteger否10000[1000, 60000]获取 spec_url 的 HTTP 请求超时时间（毫秒）。
verbose_errorsboolean否false为 true 时，在响应体中返回详细的校验错误信息。
skip_request_body_validationboolean否false跳过请求体校验。
skip_request_header_validationboolean否false跳过请求头校验。
skip_query_param_validationboolean否false跳过查询参数校验。
skip_path_params_validationboolean否false跳过路径参数校验。
reject_if_not_matchboolean否true为 true 时，拒绝校验失败的请求；为 false 时，仅记录校验失败日志并放行请求。
rejection_status_codeinteger否400[400, 599]请求校验失败时返回的 HTTP 状态码。

* spec 与 spec_url 必须且只能设置其中一个。

插件元数据#

以下元数据属性通过插件元数据 API 进行配置，作用于插件级别：

名称类型必选项默认值有效值描述
spec_url_ttlinteger否3600≥ 1从 spec_url 获取的规范的缓存时间（秒）。

示例#

以下示例演示了如何在不同场景中使用 oas-validator 插件。

note
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

使用内联规范校验请求#

以下示例演示如何使用内联 OpenAPI 3.x 规范校验请求。不符合规范的请求将以 400 响应被拒绝。

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "oas-validator-route",
    "uri": "/api/v3/*",
    "plugins": {
      "oas-validator": {
        "spec": "{\"openapi\":\"3.0.2\",\"info\":{\"title\":\"Pet API\",\"version\":\"1.0.0\"},\"paths\":{\"/api/v3/pet\":{\"post\":{\"requestBody\":{\"required\":true,\"content\":{\"application/json\":{\"schema\":{\"type\":\"object\",\"required\":[\"name\"],\"properties\":{\"name\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}}}}}},\"responses\":{\"200\":{\"description\":\"OK\"}}}}}}",
        "verbose_errors": true
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {"httpbin.org:80": 1}
    }
  }'

发送一个包含必填 name 字段的合法请求：

curl -i "http://127.0.0.1:9080/api/v3/pet" -X POST \
  -H "Content-Type: application/json" \
  -d '{"name": "doggie", "status": "available"}'

将收到来自上游的 200 响应。

发送一个缺少必填 name 字段的非法请求：

curl -i "http://127.0.0.1:9080/api/v3/pet" -X POST \
  -H "Content-Type: application/json" \
  -d '{"status": "available"}'

将收到包含校验错误信息的 400 响应。

使用远程规范 URL 校验请求#

以下示例演示如何从远程 URL 获取 OpenAPI 规范。规范在首次获取后会被缓存，缓存时长由插件元数据的 spec_url_ttl 参数决定。

配置插件元数据以设置远程规范的缓存时间：

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/oas-validator" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "spec_url_ttl": 600
  }'

创建带有 oas-validator 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${admin_key}" \
  -d '{
    "id": "oas-validator-url-route",
    "uri": "/api/v3/*",
    "plugins": {
      "oas-validator": {
        "spec_url": "https://petstore3.swagger.io/api/v3/openapi.json",
        "ssl_verify": false,
        "verbose_errors": true
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {"httpbin.org:80": 1}
    }
  }'

发送一个不符合 Petstore 规范的请求：

curl -i "http://127.0.0.1:9080/api/v3/pet" -X POST \
  -H "Content-Type: application/json" \
  -d '{"invalid": "body"}'

由于 verbose_errors 设置为 true，将收到包含详细校验错误信息的 400 响应。