OAS Validation

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

curl -X POST http://localhost:8001/services/SERVICE_NAME|SERVICE_ID/plugins \
    --data "name=oas-validation"  \
    --data "config.api_spec={your API specification}" \
    --data "config.verbose_response=true"

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: oas-validation-example
config: 
  api_spec: {your API specification}
  verbose_response: true
plugin: oas-validation

apiVersion: v1
kind: Service
metadata:
  name: SERVICE_NAME|SERVICE_ID
  labels:
    app: SERVICE_NAME|SERVICE_ID
  annotations:
    konghq.com/plugins: oas-validation-example
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: SERVICE_NAME|SERVICE_ID
  selector:
    app: SERVICE_NAME|SERVICE_ID

plugins:
- name: oas-validation
  service: SERVICE_NAME|SERVICE_ID
  config: 
    api_spec: {your API specification}
    verbose_response: true

curl -X POST http://localhost:8001/routes/ROUTE_NAME|ROUTE_ID/plugins \
  --data "name=oas-validation"  \
    --data "config.api_spec={your API specification}" \
    --data "config.verbose_response=true"

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: oas-validation-example
config: 
  api_spec: {your API specification}
  verbose_response: true
plugin: oas-validation

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ROUTE_NAME|ROUTE_ID
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: oas-validation-example
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          service:
            name: echo
            port:
              number: 80

plugins:
- name: oas-validation
  route: ROUTE_NAME
  config: 
    api_spec: {your API specification}
    verbose_response: true

curl -X POST http://localhost:8001/plugins/ \
  --data "name=oas-validation"  \
    --data "config.api_spec={your API specification}" \
    --data "config.verbose_response=true"

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-oas-validation>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  api_spec: {your API specification}
  verbose_response: true
plugin: oas-validation

plugins:
- name: oas-validation
  config: 
    api_spec: {your API specification}
    verbose_response: true

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

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 in kong.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.

1. 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'
   

2. Create a wildcard route called Petstore-Route:

    curl -X POST http://<admin-hostname>:8001/services/Petstore-Service/routes \
        --data name='Petstore-Route' \
        --data paths='/.*'
   

3. 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
   

4. 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.

1. 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
    }
   

2. 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": {}
    }