Skip to content

A Kong plugin for validating HTTP requests against OpenAPI specifications.

License

Notifications You must be signed in to change notification settings

nawaz1991/kong-plugin-oasvalidator

Repository files navigation

🛡️ OASValidator Kong Plugin

kong-plugin-oasvalidator is a Kong plugin that validates incoming HTTP requests against OpenAPI specifications. It offers a granular level of validation including request, body, path parameters, query parameters, header parameters, and routes.

📚 Table of Contents

  1. Features
  2. Prerequisites
  3. Installation
  4. Configuration
  5. Usage
  6. Validation Strategies
  7. Troubleshooting
  8. License

🌟 Features

  • Validates the entire request or individual parts like body, path, query, and header.
  • Low latency and high efficiency.
  • Highly configurable through Kong's admin API.

🔧 Prerequisites

  • Kong >= 2.x.x
  • LUA >= 5.1

📦 Installation

Install it as a LuaRocks package:

luarocks install oasvalidator

⚙️ Configuration

You can add the plugin with the following request:

curl -X POST http://localhost:8001/services/{serviceName|Id}/plugins \
--data "name=oasvalidator" \
--data "config.oas_spec_path=/path/to/oas/spec" \
--data "config.validate_request=true" \
--data "config.validate_body=false" \
--data "config.validate_path_params=false" \
--data "config.validate_query_params=false" \
--data "config.validate_header_params=false" \
--data "config.validate_route=false"

Or, you can use Declarative (YAML) to configure:

_services:
- name: my-service
  url: http://example.com
  plugins:
    - name: oasvalidator
      config:
        oas_spec_path: "/path/to/oas/spec"
        validate_request: true
        validate_body: false
        validate_path_params: false
        validate_query_params: false
        validate_header_params: false
        validate_route: false

Schema

-- Refer to the schema.lua file for the full configuration schema

Parameters

  • oas_spec_path: Path to the OpenAPI specification file (required).
  • validate_request: Validate the entire request (super set of all validations). Default is true.
  • validate_body: Validate request body against the OpenAPI spec. Default is false.
  • validate_path_params: Validate path parameters against the OpenAPI spec. Default is false.
  • validate_query_params: Validate query parameters against the OpenAPI spec. Default is false.
  • validate_header_params: Validate header parameters against the OpenAPI spec. Default is false.
  • validate_route: Validate route against the OpenAPI spec. Default is false.

🔍 Usage

After installation and configuration, the plugin will validate incoming requests based on the rules you've set.

📜 Validation Strategies

  • Validate Request: This is a super set of all other validators. If this is enabled, all other validators should be set to false.
  • Individual Validations: You can also use individual validators for the body, path parameters, query parameters, header parameters, and routes.

🛠️ Troubleshooting

Check the Kong error logs for any issues. Error logs provide detailed information about what went wrong, aiding in rapid debugging.

tail -f /usr/local/kong/logs/error.log

📄 License

This project is licensed under the MIT License. See the LICENSE file for the full license text.

© 2023 Muhammad Nawaz. All Rights Reserved.