News New Look, Same Vision: KrakenD’s Website Redesign

You are viewing a previous version of KrakenD Enterprise Edition (v2.1), go to the latest version

Document updated on Apr 26, 2022

Import and Export OpenAPI

Import and Export OpenAPI

The OpenAPI generators are command-line utilities embedded in the KrakenD binary, offering OpenAPI import and export capabilities. The OpenAPI generator allows you to:

  • Export to OpenAPI: From an existing KrakenD configuration, you can automatically generate the API documentation in OpenAPI format.
  • Import from OpenAPI: From an existing OpenAPI spec, you can generate the initial KrakenD configuration to start working.

The OpenAPI-supported version is Swagger v2 (not OAS3) in both functionalities.

Exporting to OpenAPI

The command needed to generate the OpenAPI specification is krakend generate openapi:

Generating the documentation 

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

Version: 

Generates the OpenAPI descriptor for the gateway based on the configuration file.
Usage:
  krakend generate openapi [flags]
Examples:
krakend generate openapi -c config.json -o openapi.json
Flags:
  -h, --help   help for openapi
Global Flags:
  -c, --config string   Path to the configuration filename
  -d, --debug           Enable the debug
  -o, --out string      Path to the generated result. (default "out.json")
  -a, --audience        Filter out endpoints non matching the given "audience"

When you don’t add any specific details in the configuration, KrakenD will generate a basic version of the OpenAPI specification, containing the declared endpoints in the gateway.

To enrich the OpenAPI output, see how to add OpenAPI information to your endpoints.

The swagger output can be saved statically and served to end-users once it is generated. An excellent place to develop the specs is in your CI/CD pipeline.

Importing from OpenAPI

If what you want to do 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:

Importing an OpenAPI file 

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

Version: 

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
  -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")

For instance, you could generate a krakend.json from an existing openapi.yaml like this:

Term 

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

The generated configuration contains any json-schema definitions that KrakenD can extract from the OpenAPI spec and forces users of the newly generated KrakenD API to use the declared types properly.

Mock server

If your backend services do not exist yet or are not ready, you can import the OpenAPI configuration to KrakenD and let KrakenD respond with mock data so that you can reply to HTTP calls right away.

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

Term 

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

Unresolved issues?

The documentation is only a piece of the help you can get! Whether you are looking for Open Source or Enterprise support, see more support channels that can help you.

See all support channels