deck file 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

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

The following sections list some best practices for conversion from OAS format into Kong declarative files.

ID Generation

The openapi2kong command generates 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 a 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

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