Validate HTTP requests and responses based on an API Specification. Supports both Swagger v2 and OpenAPI v3 specifications JSON request and response bodies, with support for schema definitions described using JSON Schema draft v4. For JSON Schema draft 4 type schemas, see the JSON Schema documentation for details on the format and examples.
In Kong Gateway versions 3.1.0.0-3.1.1.1, this plugin is not enabled by default. Upgrade to 3.1.1.2, or manually enable the plugin.
Configuration Reference
This plugin is compatible with DB-less mode.
In DB-less mode, you configure Kong Gateway declaratively. Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:
- Setting a target's health status in the load balancer
- Validating configurations against schemas
- Uploading the declarative configuration using the
/config
endpoint
Example plugin configuration
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
Form Parameter | Description |
---|---|
name
required Type: string |
The name of the plugin, in this case oas-validation . |
service.name or service.id
Type: string |
The name or ID of the service the plugin targets.
Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint.
Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins . |
route.name or route.id
Type: string |
The name or ID of the route the plugin targets.
Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint.
Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins . |
enabled
Type: boolean Default value: true |
Whether this plugin will be applied. |
config.api_spec
required Type: string |
The API specification defined using either Swagger or the OpenAPI. This can be either a JSON or YAML based file. If using a YAML file, the spec needs to be URL encoded to preserve the YAML format. |
config.validate_request_uri_params
optional Type: boolean Default value: true
|
If set to true, validates URI parameters in the request against the API specification. |
config.validate_request_header_params
optional Type: boolean Default value: true
|
If set to true, validates HTTP header parameters against the API specification. |
config.validate_request_query_params
optional Type: boolean Default value: true
|
If set to true, validates query parameters against the API specification. |
config.validate_request_body
optional Type: boolean Default value: true
|
If set to true, validates the request body content against the API specification. |
config.notify_only_request_validation_failure
optional Type: boolean Default value: false
|
If set to true, notifications via event hooks are enabled, but request based validation failures don’t affect the request flow. |
config.validate_response_body
optional Type: boolean Default value: false
|
If set to true, validates the response from the upstream services against the API specification. If validation fails, it results in an |
config.notify_only_response_body_validation_failure
optional Type: boolean Default value: false
|
If set to true, notifications via event hooks are enabled, but response validation failures don’t affect the response flow. |
config.header_parameter_check
required Type: boolean Default value: false
|
If set to true, checks if HTTP header parameters in the request exist in the API specification. |
config.query_parameter_check
required Type: boolean Default value: false
|
If set to true, checks if query parameters in the request exist in the API specification. |
config.allowed_header_parameters
optional Type: string Default value: Host,Content-Type,User-Agent,Accept,Content-Length
|
List of header parameters in the request that will be ignored when performing HTTP header validation. These are additional headers added to an API request beyond those defined in the API specification. For example, you might include the HTTP header |
config.verbose_response
optional Type: boolean Default value: false
|
If set to true, returns a detailed error message for invalid requests & responses. This is useful while testing. |
Enable the plugin
In Kong Gateway versions 3.1.0.0-3.1.1.1, this plugin is not enabled by default.
To enable the plugin, use one of the following methods:
- Package install: Set
plugins=bundled,oas-validation
inkong.conf
before starting Kong - Docker: Set
KONG_PLUGINS=bundled,oas-validation
in the environment - Kubernetes: Set
KONG_PLUGINS=bundled,oas-validation
using these instructions
Tutorial
This example tutorial steps you through ensuring an API request conforms to the associated API specification. This example uses the sample Petstore spec.
-
Create a service called
Petstore-Service
:curl -X POST http://<admin-hostname>:8001/services/ \ --data name='Petstore-Service' \ --data url='https://petstore.swagger.io/v2'
-
Create a wildcard route called
Petstore-Route
:curl -X POST http://<admin-hostname>:8001/services/Petstore-Service/routes \ --data name='Petstore-Route' \ --data paths='/.*'
-
Enable the Validation plugin on the service you configured:
curl -X POST http://<admin-hostname>:8001/services/Petstore-Service/plugins \ --data name='oas-validation' \ --data config.api_spec='<copy contents of https://petstore.swagger.io/v2/swagger.json here>' \ --data config.verbose_response=true
-
Test the Validation plugin. The request resource expects a status query parameter, which is missing from the following request:
curl -X GET "http://<proxy-host>:8000/pet/findByStatus" \ -H "accept: application/json"
The response includes a verbose error response, since we have enabled this option in the plugin configuration:
HTTP/1.1 400 Bad Request Content-Length: 106 Content-Type: application/json; charset=utf-8 Date: Tue, 03 May 2022 20:45:00 GMT Server: kong/2.8.0.0-internal-preview-enterprise-edition X-Kong-Response-Latency: 2 { "message": "query 'status' validation failed with error: 'required parameter value not found in request'" }
Event hooks
Event hooks are outbound calls from Kong Gateway. With event hooks, Kong Gateway can communicate with target services or resources, letting the target know that an event was triggered. Refer to the event hooks example documentation for more information on event hooks.
For the Validation plugin, event hook events can be enabled when a Validation fails for all request parameters, that is URI, Header, & Query parameters and Request body, and/or for Response body from the Upstream Service.
-
Add an event hook for the Validation plugin:
curl -i -X POST http://{HOSTNAME}:8001/event-hooks \ -d source=oas-validation \ -d event=validation-failed \ -d handler=webhook \ -d config.url={WEBHOOK_URL}
Response:
HTTP/1.1 201 Created .. { "config": { "headers": {}, "url": {WEBHOOK_URL}, "ssl_verify": false, "secret": null }, "id": "3fe43989-6cf1-4936-bd5d-b7774ca52ad8", "source": "oas-validation", "event": "validation-failed", "handler": "webhook", "snooze": null, "on_change": null, "created_at": 1649732398 }
-
Force a validation failure to a service or route to which the Validation plugin is applied. The Webhook URL will receive a response with JSON payload.
The following is an example JSON response which includes the forwarded IP address, service, consumer, and and error message:
{ "ip": "10.0.2.2", "source": "oas-validation", "err": "query 'status' validation failed with error: 'required parameter value not found in request'", "event": "validation-failed", "service": { "ws_id": "7eebecc0-064e-4890-99cf-0c816280a68e", "enabled": true, "retries": 5, "read_timeout": 60000, "protocol": "https", "id": "6792ec72-67b2-4960-96b1-e7564dda3178", "connect_timeout": 60000, "name": "petstore-service", "port": 443, "host": "petstore.swagger.io", "updated_at": 1649391578, "path": "/v2/", "write_timeout": 60000, "created_at": 1647993371 }, "consumer": {} }