Skip to content
Kong Docs are moving soon! Our docs are migrating to a new home. You'll be automatically redirected to the new site in the future. In the meantime, view this page on the new site!
Kong Logo | Kong Docs Logo
  • Docs
    • Explore the API Specs
      View all API Specs View all API Specs View all API Specs arrow image
    • Documentation
      API Specs
      Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong AI Gateway
      Multi-LLM AI Gateway for GenAI infrastructure
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Kong Gateway Operator
      Manage your Kong deployments on Kubernetes using YAML Manifests
      Insomnia
      Collaborative API development platform
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      AI's icon
      AI
      Govern, secure, and control AI traffic with multi-LLM AI Gateway plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
decK
  • Home icon
  • decK
  • File
  • openapi2kong
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Kong AI Gateway
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • Introduction
    • Overview
    • Configuration Options
    • Support Policy
    • Security Policy
  • Changelog
  • Installation
    • Overview
    • Binary
    • Docker
    • GitHub Actions
  • Get Started
  • Managing Kong Gateway
    • Overview
    • Konnect Configuration
    • Configure Authentication
    • Ping
    • Backup
    • Diff
    • Sync
    • Apply
    • Reset
    • Validate
    • RBAC
    • Workspaces
    • Tags
    • De-duplicate Plugin Configuration
    • Object Defaults
    • Sensitive Data
  • decK Files
    • Overview
    • Config Generation
      • openapi2kong
      • kong2kic
      • kong2tf
    • Linting
    • File Manipulation
      • Overview
      • Update Values
      • Plugins
      • Tags
      • Namespace
    • Combining Files
      • Merge
      • Render
    • Validate
    • Convert
  • APIOps
    • Overview
    • Continuous Integration
    • Federated Config
  • Reference
    • Entities
    • FAQ
    • Gateway 3.0 Upgrade
    • Environment Variables
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Get started
  • Best practices
    • ID Generation
    • Adding plugins
  • Custom x-kong extensions

openapi2kong

The openapi2kong command converts an OpenAPI specification to Kong’s declarative configuration format.

  • A Service is created, pointing to the URLs in the servers block
  • One route per operationId is created
  • If an openIdConnect securityScheme is present, an openid-connect plugin will be generated

Get started

Converting an OpenAPI file to a Kong declarative configuration can be done in a single command:

deck file openapi2kong --spec oas.yaml --output-file kong.yaml

Best practices

ID Generation

The openapi2kong command will generate a declarative configuration file that contains an id for each entity. This ensures that even if the entity name (or any other identifying parameter) changes, it will update an entity in Kong Gateway rather than deleting then recreating an entity.

If you have an existing Kong Gateway instance, you can use the --inso-compatible flag to skip ID generation. In this instance, decK will match entities on a best effort basis using the name field.

If you have multiple teams using the same names and operationId values in their specifications, you can specify the --uuid-base flag to set a custom namespace when generating IDs.

To learn more about ID generation, see the openapi2kong GitHub documentation.

Adding plugins

openapi2kong allows you to configure plugins directly in your OpenAPI specification by providing an x-kong-plugin-PLUGIN-NAME annotation at the root level to add it to the service, at the path level to add it to all routes on that path, or on an operation to add it to a specific route.

However, we do not recommend using this functionality. Routing and policy enforcement are generally owned by different teams, and you do not want to publish plugin configuration in an OpenAPI specification that is shared with customers.

We recommend using the add-plugin command after the openapi2kong command has been run.

If you really want to embed plugin configuration in your OpenAPI specification, here is an example extension that adds the request-termination plugin to a route:

x-kong-request-termination:
  status_code: 403
  message: So long and thanks for all the fish!

There are two exceptions to this recommendation:

  • Configuring OpenID Connect scopes
  • Dynamically generating request validator plugins for all endpoints

Configuring OpenID Connect scopes

OpenID Connect allows you to check for specific scopes when accessing a route. App development teams know which scopes are required for the paths their application serves.

To define scopes on a per-path level, use the x-kong-security-openid-connect annotation at the same level as operationId.

x-kong-security-openid-connect:
  config:
    scopes_required: ["scope1", "scope2"]

Dynamic request-validator plugin configuration

The Kong request-validator plugin can validate incoming requests against a user-provided JSON schema.

The plugin can be configured manually, but openapi2kong can use the provided OpenAPI specification to configure the request-validator plugin for all routes automatically. To enable this behavior, add the x-kong-plugin-request-validator at the root level to add it to all routes, at the path level to add it to all routes on that path, or on an operation to add it to a specific route.

Omitting the body_schema and parameter_schema configuration options tells openapi2kong to automatically inject the schema for the current endpoint when generating a Kong Gateway declarative configuration file.

x-kong-plugin-request-validator:
  config:
    verbose_response: true

Custom x-kong extensions

The openapi2kong command supports the following custom x-kong extensions to customize the declarative configuration file generation:

Annotation Description
x-kong-tags Specify the tags to use for each Kong Gateway entity generated. Tags can be overridden when doing the conversion. This can only be specified at the document level.
x-kong-service-defaults The defaults for the services generated from the servers object in the OpenAPI spec. These defaults can also be added to the path and operation objects, which will generate a new service entity.
x-kong-upstream-defaults The defaults for upstreams generated from the servers object in the OpenAPI spec. These defaults can also be added to the path and operation objects, which will generate a new service entity.
x-kong-route-defaults The defaults for the routes generated from paths in the OpenAPI spec.
x-kong-name The name for the entire spec file. This is used for naming the service and upstream objects in Kong Gateway. If not given, it will use the info.title field to name these objects, or a random UUID if the info.title field is missing. Names are converted into valid identifiers. This directive can also be used on path and operation objects to name them. Similarly to operationId, each x-kong-name must be unique within the spec file.
x-kong-plugin-<kong-plugin-name> Directive to add a plugin. The plugin name is derived from the extension name and is a generic mechanism that can add any type of plugin. This plugin is configured on a global level for the OpenAPI spec. As such, it is configured on the service entity, and applies on all paths and operations in this spec.

The plugin name can also be specified on paths and operations to override the config for that specific subset of the spec. In that case, it is added to the generated route entity. If new service entities are generated from path or operation objects, the plugins are copied over accordingly (for example, by having servers objects, or upstream or service defaults specified on those levels).

A consumer can be referenced by setting the consumer field to the consumer name or ID.

Note: Since the plugin name is in the key, only one instance of each plugin can be added at each level.
securitySchemes.[...].x-kong-security-openid-connect Specifies that the OpenID Connect plugin is to be used to implement this security scheme object. Any custom configuration can be added as usual for plugins.
components.x-kong Reusable Kong Gateway configuration components. All x-kong references must be under this key. It accepts the following referenceable elements:
• x-kong-service-defaults
• x-kong-upstream-defaults
• x-kong-route-defaults
• x-kong-plugin-[...] plugin configurations
• x-kong-security-[...] plugin configurations

For more information and examples of these annotations, see the commented example openapi2kong OAS.

Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    Powering the API world

    Increase developer productivity, security, and performance at scale with the unified platform for API management, service mesh, and ingress controller.

    • Products
      • Kong Konnect
      • Kong Gateway Enterprise
      • Kong Gateway
      • Kong Mesh
      • Kong Ingress Controller
      • Kong Insomnia
      • Product Updates
      • Get Started
    • Documentation
      • Kong Konnect Docs
      • Kong Gateway Docs
      • Kong Mesh Docs
      • Kong Insomnia Docs
      • Kong Konnect Plugin Hub
    • Open Source
      • Kong Gateway
      • Kuma
      • Insomnia
      • Kong Community
    • Company
      • About Kong
      • Customers
      • Careers
      • Press
      • Events
      • Contact
  • Terms• Privacy• Trust and Compliance
© Kong Inc. 2025