A tool to batch-convert OpenAPI 3.0 files to a flexible KrakenD configuration
Report Bug
·
Request Feature
A tool to batch-convert OpenAPI 3.0 files to a flexible KrakenD configuration
Below are the instructions for running the API for development and general usage.
Install the dependencies using:
$ pip install -r requirements.txtRun main.py to execute the converter:
Usage: python -m app.main [OPTIONS] INPUT_FOLDER OUTPUT_FOLDER
The converter CLI command
╭─ Arguments ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ * input_folder TEXT Input folder that contains all the OpenAPI specifications [required] │
│ * output_folder TEXT Output folder [required] │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --debug Enable debug mode │
│ --env TEXT Choose the environment (prod, dev, etc..) │
│ --disable-automatic-versioning Disable versioning based on 'version' field in OpenAPI specification and use filename based-versioning instead. │
│ --help Show this message and exit. │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯- Place the OpenAPI files you wish to convert in the input folder
- Run main.py
- Find the config folder in
output
Depending on your authorization method, it might be possible to automatically add authorization headers to the endpoints that require them. Below is a table of the supported authorization schemes.
| Method | Supported | Header name |
|---|---|---|
| HTTP (Basic) | Yes | Authorization |
| HTTP (Bearer) | Yes | Authorization |
| API Keys (header) | Yes | Defined in OpenAPI spec |
| API Keys (cookie) | No | |
| OAuth 2.0 (Implicit) | Yes | Authorization |
| OAuth 2.0 (Authorization code) | No | |
| OAuth 2.0 (Password) | No | |
| OAuth 2.0 (Client Credentials) | No | |
| OpenID Connect Discovery | No |
By default, the converter will automatically version your APIs based on the version field inside your OpenAPI
specification.
The converter can handle manual versioning as well by using the --disable-automatic-versioning flag.
To version your APIs, you have to name the OpenAPI file in the <api>.<version>.json.
Example:
F1.V1.json will create the API on /f1/v1
If you do not wish to use versioning, you can just name your file as normal and run the converter with
the --disable-automatic-versioning flag. Do note that if you add .v to the
OpenAPI name, it will create a version.
Using the --env flag, you can specify the environment you wish to use. This matches the description field inside the
servers object of the OpenAPI specifications.
It's possible to customize the default configuration by adding a config folder with the configuration files inside
it. To view the default configuration files, see the files inside app/config.
To view an example of this, see KrakenD Cloud Run service account plugin
Below are the configuration files that you can use to configure KrakenD to your liking.
| File | Function |
|---|---|
| backend.json | The configuration for the backend section in an endpoint. See Declaring and connecting to backends |
| endpoint.json | The configuration for the endpoint section in an endpoint file. See Creating API endpoints |
| krakend.json | The general KrakenD configuration. Refer to the KrakenD docs for more information. |
| Dockerfile | The Dockerfile to build a Docker image of the final KrakenD gateway. See Generating a Docker artifact |
It's possible to use this in a GitHub action to automatically generate the configuration with provided specifications.
Running this action will create an artifact named krakend-config. To use this artifact in other jobs, you
can use actions/download-artifact@v2 to download the action. This can be handy if you wish to automatically deploy
it to a cloud service, like Google Cloud Run.
The converter will automatically create a full Docker-ready configuration. All you have to do is build the Docker image and run it.
Below is a basic example of how to use the converter
name: Convert Specs to KrakenD config
on: workflow_dispatch
jobs:
convert:
runs-on: ubuntu-latest
steps:
- name: Convert specs to KrakenD config
uses: f1betting/OpenAPItoKrakenD@v2
with:
input-folder: inputThere are a few configurations options possible. These are the ones that are available to use:
| Name | Required | Description |
|---|---|---|
| input-folder | Yes | The input folder that contains the OpenAPI specs and optional custom configuration files |
| environment | No | Set the backend target URL to the description of the server object inside the OpenAPI specification (picks the first entry if not specified) |
| disable-versioning | No | Disable automatic versioning based on OpenAPI specifications |
For a more detailed example, which automatically deploys the KrakenD gateway to Google Cloud Run, see automatic cloud run deployment.
You can find an example using a custom configuration in KrakenD Cloud Run service account plugin
Distributed under the MIT License. See LICENSE.md for more information.