How can OpenAPI be used with Kong API Gateway? #

Kong Gateway is one of the most widely deployed open-source API gateways, used by organizations to manage, secure, and observe API traffic. Kong uses a plugin architecture that can add authentication, rate limiting, logging, transformation, and other capabilities to API traffic without modifying the API implementation. OpenAPI and Kong integrate naturally: the OpenAPI document describes the API’s capabilities and contract, while Kong enforces policies on traffic to and from that API. This article covers the primary ways OpenAPI and Kong can be used together.

Importing OpenAPI Documents into Kong #

Kong’s configuration model is built around Services (upstream API implementations) and Routes (URL patterns that match incoming requests to a service). Historically, configuring Kong required defining Services, Routes, and Plugins manually via the Kong Admin API, a declarative YAML configuration, or a GUI.

Kong now supports importing OpenAPI documents to generate this configuration automatically. The two primary methods are Insomnia (Kong’s API design tool) and deck (Kong’s declarative configuration CLI).

Method 1: deck with openapi2kong #

deck is Kong’s official declarative configuration management tool. It includes the deck file openapi2kong command that converts an OpenAPI document into a Kong declarative configuration file:

deck file openapi2kong \
  --spec openapi.yaml \
  --output-file kong.yaml

This generates a kong.yaml file containing:

• A service corresponding to the API’s upstream server (servers[0].url)
• A route for each operation in the OpenAPI document, with the correct path pattern and HTTP method
• Optionally, plugins derived from OpenAPI security schemes

The generated configuration can then be synchronized to a running Kong instance:

deck gateway sync kong.yaml

This workflow makes the OpenAPI document the source of truth for Kong’s routing configuration. When new endpoints are added to the OpenAPI document, regenerating and syncing the deck configuration automatically updates Kong’s routing table.

Method 2: Kong Insomnia #

Insomnia is Kong’s API design and testing tool. Insomnia can import OpenAPI documents and generate a test workspace (similar to Postman), but it also has a design flow that publishes OpenAPI documents to Kong Konnect (Kong’s managed cloud platform) directly. Teams use Insomnia to design the API in OpenAPI, test it, and deploy the gateway configuration from a single tool.

Generating Routes from OpenAPI Paths #

The openapi2kong conversion maps OpenAPI path items to Kong routes. Path parameters are converted to Kong path variable syntax:

Each route is configured with the HTTP methods from the OpenAPI operation (e.g., a route for GET /users will only match GET requests).

Authentication from OpenAPI Security Schemes #

OpenAPI security schemes can be used to drive Kong’s authentication plugin configuration. The openapi2kong tool translates common security schemes:

• http bearer → Kong jwt plugin
• apiKey in header → Kong key-auth plugin
• oauth2 → Kong oauth2 plugin

For example, an OpenAPI document with:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []

Can generate a Kong configuration that applies the jwt plugin to all routes derived from the document.

Rate Limiting from OpenAPI Extensions #

Kong supports OpenAPI extension fields (prefixed with x-) to carry Kong-specific configuration that is not expressible in standard OpenAPI. This allows API designers to specify rate limiting, plugin configuration, and other gateway settings directly in the OpenAPI document:

paths:
  /search:
    get:
      summary: Search products
      x-kong-plugin-rate-limiting:
        enabled: true
        config:
          minute: 100
          hour: 1000
          policy: local
      responses:
        "200":
          ...

The deck file openapi2kong command processes these extensions and includes the corresponding plugin configuration in the generated Kong declarative config.

Request Validation Plugin #

Kong’s Request Validator plugin can validate incoming requests against the parameter and request body schemas defined in an OpenAPI document. This moves validation to the gateway layer, before the request reaches the upstream API:

# Kong declarative config with request validation
services:
  - name: my-api
    url: http://api.internal
    routes:
      - name: create-user
        methods: [POST]
        paths: [/users]
        plugins:
          - name: request-validator
            config:
              body_schema: |
                {
                  "type": "object",
                  "required": ["email", "name"],
                  "properties": {
                    "email": {"type": "string", "format": "email"},
                    "name": {"type": "string"}
                  }
                }                
              verbose_response: true

When the deck configuration is generated from OpenAPI, request schemas from requestBody can be included in the request validator plugin configuration, enabling automatic enforcement of input validation at the gateway.

OAS Validation Plugin (Kong Enterprise) #

Kong Enterprise (the commercial version) includes the OAS Validation plugin, which takes the entire OpenAPI document as its configuration and validates both request and response against the spec in real time. This provides automatic contract enforcement at the gateway level without needing to extract and duplicate schemas into separate plugin configurations.

CI/CD Integration #

The OpenAPI → Kong workflow integrates naturally into CI/CD pipelines:

# GitHub Actions example
jobs:
  deploy-gateway:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate OpenAPI document
        run: npx @stoplight/spectral-cli lint openapi.yaml --ruleset .spectral.yaml

      - name: Convert OpenAPI to Kong config
        run: deck file openapi2kong --spec openapi.yaml --output-file kong.yaml

      - name: Diff against current gateway config
        run: deck gateway diff kong.yaml

      - name: Sync to Kong
        run: deck gateway sync kong.yaml
        env:
          KONG_ADDR: ${{ secrets.KONG_ADMIN_URL }}
          KONG_TOKEN: ${{ secrets.KONG_ADMIN_TOKEN }}

This pipeline validates the OpenAPI document with Spectral, converts it to a Kong configuration, shows a diff of what will change, and then syncs the changes to the running gateway. The OpenAPI document becomes the single source of truth for both the API contract and the gateway configuration.

Konnect API Hub #

Kong Konnect (Kong’s cloud platform) includes an API Hub — a developer portal where API consumers can browse available APIs and their documentation. OpenAPI documents uploaded to Konnect are rendered as interactive API documentation (powered by Insomnia’s rendering engine), providing a built-in developer portal without additional tooling.

Conclusion #

Kong and OpenAPI complement each other at every stage of the API lifecycle. The OpenAPI document defines the API contract; Kong enforces policies on traffic to and from that API. With tools like deck and openapi2kong, the OpenAPI document can drive Kong’s routing configuration, authentication setup, and request validation plugin configuration automatically. Integrated into a CI/CD pipeline, this approach eliminates the drift between API documentation and gateway configuration, ensuring that what is documented and what is enforced are always in sync.

Last updated on April 30, 2026.