oas-validator
Validates requests against an OpenAPI document; responses are not checked.
oas-validatorPriority 512What it does
oas-validator reads each request on the route against an OpenAPI document before it is passed on. The document is Written here, under OpenAPI document, or Fetched from a URL, under Document URL. A request the document does not allow is answered with Rejection status code, 400 unless you change it.
Only the request is checked, never what the backend answers. A request to a path the document does not list is refused too, so the document has to describe every path the route takes.
When to use it
- An orders API that already publishes its OpenAPI description, where a call to
/orderswithout acustomer_idshould stop at the gateway. - A description the backend team keeps and serves at an address of its own, fetched under Document URL so the route follows each new version.
- Partners who build against your published description and should be told which parameter they got wrong, with Say why the request was refused on.
- A backend that fails on calls it was never designed for, kept behind the same description its clients are given.
Not for checking the body or the headers against a JSON Schema of your own — see request-validation (Validates request headers and body against a JSON Schema).
Set it up
Refuse requests that do not match the API description written here
Under Basics choose Written here and set OpenAPI document to {
"openapi": "3.0.0",
"info": {
"title": "Orders",
"version": "1.0.0"
},
"paths": {
"/orders": {
"get": {
"parameters": [
{
"name": "customer_id",
"in": "query",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "the customer's orders"
}
}
}
}
}
}. Under Behavior set Rejection status code to 422 and turn on Say why the request was refused.
{
"spec": "{\n \"openapi\": \"3.0.0\",\n \"info\": {\n \"title\": \"Orders\",\n \"version\": \"1.0.0\"\n },\n \"paths\": {\n \"/orders\": {\n \"get\": {\n \"parameters\": [\n {\n \"name\": \"customer_id\",\n \"in\": \"query\",\n \"required\": true,\n \"schema\": {\n \"type\": \"string\"\n }\n }\n ],\n \"responses\": {\n \"200\": {\n \"description\": \"the customer's orders\"\n }\n }\n }\n }\n }\n}",
"rejection_status_code": 422,
"verbose_errors": true
}
More scenarios
Fetch the API description from a URL and refuse requests that do not match it
Under Basics choose Fetched from a URL and set Document URL to https://specs.example.com/orders/openapi.json. Under Behavior set Rejection status code to 422 and turn on SSL verify.
{
"spec_url": "https://specs.example.com/orders/openapi.json",
"ssl_verify": true,
"rejection_status_code": 422
}
Fetch the description again every ten minutesenvironment-wide settings
Set How long a fetched document is kept to 600 seconds.
{
"spec_url_ttl": 600
}
Things to know
- OpenAPI document — In the example the document makes
customer_ida required query parameter of/orders. A request without it is answered422naming the missing parameter, and/orders?customer_id=42is answered200. - OpenAPI document — Stored as JSON and read as an OpenAPI document only at the first request: one that is not a document of that shape is stored without a word and answers 500.
- Document URL — A document fetched from an address is applied the same way. In the example a request without
customer_idis answered422, and one that carries it is answered200. - A configuration that carries both OpenAPI document and Document URL is refused when you save.
- Refuse a request the document does not allow — Turned off, a request the document does not allow is sent to the upstream anyway and the status below is never used.
- Rejection status code — A status below
400,399for example, is refused when you save. - Say why the request was refused — Off, the refusal carries only
failed to validate request, whatever failed. - AdviceCheck the document with the OpenAPI tools your team already uses before you save it, and turn on SSL verify when it is fetched over https.
Settings
The fields as the console shows them, section by section.
Basics
Choose one:
Written here
specstringRequiredThe OpenAPI document, written as JSON (YAML is refused). A request to a path it does not list is refused.
Fetched from a URL
spec_urlstringRequiredThe address the OpenAPI document is fetched from. It is cached for the time set in the plugin's metadata.
pattern
^https?://http://specs.internal/orders/openapi.jsonBehavior
reject_if_not_matchbooleandefault truerejection_status_codeintegerdefault 400The status a refused request is answered with.
skip_request_body_validationbooleandefault falseskip_request_header_validationbooleandefault falseskip_query_param_validationbooleandefault falseskip_path_params_validationbooleandefault falseverbose_errorsbooleandefault falseOn, the refusal names the parameter or property that failed. Off, it only says the request did not validate.
spec_url_request_headersobjectHeaders sent when the document is fetched, such as an Authorization for a protected address. Stored on the engine and shown only to roles that manage this object. An object whose keys are any name, each with a string as its value.
timeoutintegerdefault 10000How long the fetch above may take. A fetch that does not finish leaves the request answered with 500.
ssl_verifybooleandefault falseUsed only while the document is fetched. Off, an https document is taken whatever certificate the server shows.
Advanced
max_req_body_sizeintegerdefault 67108864Bytes of the request body read before it is checked. A longer body is answered with 500 and never reaches the upstream.
Environment-wide settings
Set once per environment, under Plugins › oas-validator. Every oas-validator in the environment uses these.
spec_url_ttlintegerdefault 3600One setting for the whole gateway: every route that fetches its document from a URL re-fetches it once this much time has passed.