Import and Export OpenAPI

Document updated on Apr 26, 2022

The OpenAPI generator is a command-line utility embedded in the KrakenD binary, offering OpenAPI import and export capabilities (for both Swagger v2 and OAS3). The OpenAPI generator allows you to generate the documentation from a KrakenD configuration or a KrakenD configuration from an existing OpenAPI.

• The generate openapi creates OpenAPI documentation when you have a KrakenD configuration.
• The generate from openapi creates a KrakenD configuration from an OpenAPI specification file.

Exporting to OpenAPI

To generate OpenAPI documentation, the command needed is krakend generate openapi. These are the different supported options:

$krakend generate openapi -h
╓▄█                          ▄▄▌                               ╓██████▄µ
▐███  ▄███╨▐███▄██H╗██████▄  ║██▌ ,▄███╨ ▄██████▄  ▓██▌█████▄  ███▀╙╙▀▀███╕
▐███▄███▀  ▐█████▀"╙▀▀"╙▀███ ║███▄███┘  ███▀""▀███ ████▀╙▀███H ███     ╙███
▐██████▌   ▐███⌐  ,▄████████M║██████▄  ║██████████M███▌   ███H ███     ,███
▐███╨▀███µ ▐███   ███▌  ,███M║███╙▀███  ███▄```▄▄` ███▌   ███H ███,,,╓▄███▀
▐███  ╙███▄▐███   ╙█████████M║██▌  ╙███▄`▀███████╨ ███▌   ███H █████████▀
                     ``                     `'`

Version: 2.2

Generates the OpenAPI descriptor for the gateway based on the configuration file.

Usage:
  krakend generate openapi [flags]

Examples:
krakend generate openapi -a audience -c config.json -o openapi.json

Flags:
  -a, --audience string   Filter out endpoints not matching the given 'audience'.
  -h, --help              help for openapi
  -O, --oas3              Use OpenApi Spec v3.0 (defaults to Swagger v2.0)

Global Flags:
  -c, --config string   Path to the input configuration file. (default "./input.json")
  -o, --out string      Path to the generated result. (default "out.json")

The important flags are --config, pointing to your krakend.json file, and --out as the final OpenAPI file in JSON format. If you use Flexible Configuration, you need to pass as --config the file generated under FC_OUT.

After executing the command, KrakenD will generate a basic version of the OpenAPI specification containing all the declared endpoints in the gateway. To enrich the OpenAPI output, you can add OpenAPI information to your endpoints with additional metadata.

Filtering which endpoints are documented

You can filter which endpoints are documented during the generation using the --audience flag. To enable filtering, you must define the audiences in each endpoint.

You can define multiple audiences and execute the command several times, so you have different specifications to share. For instance, why would you document to final customers specific endpoints that are intended for internal usage only?

Adding OpenAPI documentation in the CI/CD process

The OpenAPI generation is a command you can add to your existing build pipeline. You can save the OpenAPI output somewhere else or even keep it inside KrakenD to serve it statically.

If you want to serve the OpenAPI file from KrakenD, use the Static Filesystem option. For instance, the following line would generate the OpenAPI file:

$mkdir -p openapi && krakend generate openapi -c krakend.json -o openapi/openapi.json

And then you could add in the configuration the option to serve it as http://krakend/oas3/openapi.json:

{
  "version": 3,
  "extra_config": {
    "plugin/http-server": {
      "name": [
        "static-filesystem"
      ],
      "static-filesystem": {
        "prefix": "/oas3/",
        "path": "/etc/krakend/openapi/"
      }
    }
  }
}

Importing from OpenAPI

If what you want, on the other hand, is to generate the KrakenD configuration when you have an existing OpenAPI file, then the command you need to use is krakend generate from openapi:

$krakend generate from openapi -h
╓▄█                          ▄▄▌                               ╓██████▄µ
▐███  ▄███╨▐███▄██H╗██████▄  ║██▌ ,▄███╨ ▄██████▄  ▓██▌█████▄  ███▀╙╙▀▀███╕
▐███▄███▀  ▐█████▀"╙▀▀"╙▀███ ║███▄███┘  ███▀""▀███ ████▀╙▀███H ███     ╙███
▐██████▌   ▐███⌐  ,▄████████M║██████▄  ║██████████M███▌   ███H ███     ,███
▐███╨▀███µ ▐███   ███▌  ,███M║███╙▀███  ███▄```▄▄` ███▌   ███H ███,,,╓▄███▀
▐███  ╙███▄▐███   ╙█████████M║██▌  ╙███▄`▀███████╨ ███▌   ███H █████████▀
                     ``                     `'`

Version: 2.2

Generates a KrakenD configuration from your OpenAPI specification.

Usage:
  krakend generate from openapi [flags]

Examples:
krakend generate from openapi -c openapi.(json|yaml) -o krakend.json -m false

Flags:
  -h, --help     help for openapi
  -O, --oas3     Use OpenApi Spec v3 (defaults to Swagger v2)
  -m, --mock     Creates an API with autogenerated mocked responses.

Global Flags:
  -c, --config string   Path to the input configuration file. (default "./input.json")
  -o, --out string      Path to the generated result. (default "out.json")

The --config flag must point to a valid JSON or YAML file with the OpenAPI specification. For instance, you could generate a krakend.json from an existing openapi.yaml like this:

$krakend generate from openapi -c ~/Downloads/openapi.yaml -o krakend.json

When you generate the configuration, KrakenD includes the following:

• All the endpoints declared in the file with no-op encoding (reverse proxy). It would be best to use another encoding to avoid coupling and use data manipulation options, but that decision is up to you and your needs.
• If the OpenAPI contains a JSON schema validation, the usage of the endpoints will enforce its schema as well using json-schema request validation.
• If there are examples and you generate them using --mock, the examples are included as a static response until you implement the final backend.
• All endpoints point to an empty host as the OpenAPI spec does not define the final backend. Except for mocked data that KrakenD points to itself.
• Security schemas (basic auth, API keys) are defined with a template for you to fill with your identity server or credentials information

In addition, if you use OAS3 format with the flag --oas3:

• Required query strings and required headers are added to the endpoint
• JWT in the security schemas

Mock server

Suppose your backend services still need to be created or are not ready. In that case, you can import the OpenAPI configuration to KrakenD and let KrakenD respond with mock data so that you can reply to HTTP calls immediately.

To create the mock data, pass the -m or --mock flag:

$krakend generate from openapi -c ~/Downloads/openapi.yaml -o krakend.json -m

Swagger v2 is no longer updated

To keep backwards compatiblity, the OpenAPI generation still uses the Swagger 2.0 export format. Adding the flag --oas3 uses the output OAS3 instead.

Nevertheless, the v2 component is considered deprecated and not receiving further updates.