Lib to convert OpenAPI specs into Kong specs
See CHANGELOG.md.
It can be installed from the repo using LuaRocks
# NOTE: this is meant to run an a Kong system, not on a standalone Lua installation
$ git clone https://github.com/kong/openapi2kong
$ cd openapi2kong
$ luarocks make
From here the CLI utility can be used as follows:
Usage: openapi2kong [OPTIONS] <input...>
Convert OpenAPI spec 3.x into Kong declarative format
--tags (default "") Comma separated list of tags to apply
--json Write output as json (yaml is the default)
--output (default "stdout")
Output file where to write to
<input...> (string) input files (either json or yaml files)
See the examples, and try to convert them. The annotations in the files explain how most of the properties work.
Each generated entity will get the tags as specified as well as the following tags:
OAS3_import
OAS3file_<filename>
Services and Upstreams are generated from the OpenAPI property servers
(which
lives on the OpenAPI
, Path
, and Operation
objects). Each service
uses
its accompanying upstream
.
The servers listed will be added to the upstream
object as targets
, but the
property may also be an empty list in which case no targets
will be generated.
NOTE 1: The server variables defined in the server url's will be substituted by their default values.
NOTE 2: A pre-requisite is that the entries in the servers
property only
differ by hostname
and port
, since a Kong service
or upstream
cannot
have multiple paths or schemes/protocols.
Defaults for the generated upstream
and service
objects can be set by using
the custom extensions x-kong-upstream-defaults
and x-kong-service-defaults
.
The properties can be specified on the OpenAPI
, Path
, and Operation
objects.
Those defaults are 'inherited' from the top down. So defaults set on an OpenAPI
top-level object will also apply to upstreams
and services
generated
from a servers
property on a Path
or Operation
object.
So to get the upstream
defaults for a servers
property on an Operation
object:
x-kong-upstream-defaults
entry of the Operation
object, orx-kong-upstream-defaults
entry of the Path
object, orx-kong-upstream-defaults
entry of the OpenAPI
object, orThis similarly applies to the service
object.
Routes are generated for each Operation
object. They are defined as regex
routes and must have an exact match.
To set default for Routes, use the x-kong-route-defaults
extension. The
inheritance/fallback order is identical to the Service defaults.
Entity naming is relevant to be able to match OpenAPI spec content with the entities in the running Kong system.
NOTE: Every name will be normalized to remove unallowed characters!
To facilitate naming there is a custom specification x-kong-name
which can
set the name of an entity.
Every entity is named in a hierarchical manner. So for example an Operation
name will be starting with the OpenAPI
name, then the Path
name, and then
the Operation
name.
Whenever a name is not unique, the second one will get a number appended, which will be incremented for each next duplicate.
The name will be set in the following order:
x-kong-name
property, or if not set fallback toopenapi.info.title
property, or if not set fallback to"openapi"
Will share the name with its parent (either an OpenAPI
, Path
, or Operation
)
The name will be the OpenAPI
object name, with appended (in the following order):
x-kong-name
property, or if not set fallback topath.summary
property, or if not set fallback to"path"
The name will be the Path
object name, with appended the operations method.
Eg. get
, post
, etc.
The Upstream
and Service
entities will get the name of the servers
property
they were derived from.
A Route
entity will get the name of its related Operation
object.
The security
property can be defined on the top-level openapi
object as well
as on operation
objects. The information contained cannot be directly mapped
onto Kong, due to the logical and/or nature of how the specs have been set up.
To overcome this Kong will only accept a single securityScheme
from the security
property.
The additional properties that Kong supports on its plugins can be configured
by using custom extensions. The custom extensions are
x-kong-security-<plugin-name>
.
Supported types are:
oauth2
openid-connect
x-kong-security-openid-connect
openIdConnect
openid-connect
x-kong-security-openid-connect
issuer
(from openIdConnectUrl
property)scopes_required
will get the combined set of scopes from the
extension defaults and the scopes from the Security Requirement
ObjectapiKey
in
property, since the Kong plugin will by default
look in header and query already. Cookie is not supported.key-auth
x-kong-security-key-auth
key_names
will get the defaults from the extension and then the
name
from the securityScheme
object will be added to that listhttp
Basic
scheme is supportedbasic-auth
x-kong-security-basic-auth
Generic plugins can be added on an operation
object. The custom extension to
use is x-kong-plugin-<plugin-name>
. The name
property is not required
(since it's already in the extension name). Optional properties not specified
will get Kong defaults.
Plugins can also be added on the OpenAPI
object level, in which case they
will be applied to every Operation
in the spec. If a plugin is specified on
both, the Operation
level one will take precedence.
This extension needs to hold an object that contains the entire plugin config.
"x-kong-plugin-key-auth": {
"name": "key-auth",
"enabled": true,
"config": {
"key_names": ["api_key", "apikey"],
"key_in_body": false,
"hide_credentials": true
}
}
References are also supported, so this is valid as well (provided the reference exists):
"x-kong-plugin-key-auth": {
"$ref": "#/components/kong/plugins/key_auth_config"
}
To enable validation the request-validation
plugin must be added to an
operation
object. You can either specify the full configuration, or have it
be auto-generated based on the OpenAPI spec.
To enable auto generation, add the plugin, but do not include the config
property. The config
property will then be auto-generated and added to
the generated spec.