Documentation
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:
$krakend generate openapi -h
╓▄█ ▄▄▌ ╓██████▄µ
▐███ ▄███╨▐███▄██H╗██████▄ ║██▌ ,▄███╨ ▄██████▄ ▓██▌█████▄ ███▀╙╙▀▀███╕
▐███▄███▀ ▐█████▀"╙▀▀"╙▀███ ║███▄███┘ ███▀""▀███ ████▀╙▀███H ███ ╙███
▐██████▌ ▐███⌐ ,▄████████M║██████▄ ║██████████M███▌ ███H ███ ,███
▐███╨▀███µ ▐███ ███▌ ,███M║███╙▀███ ███▄```▄▄` ███▌ ███H ███,,,╓▄███▀
▐███ ╙███▄▐███ ╙█████████M║██▌ ╙███▄`▀███████╨ ███▌ ███H █████████▀
`` `'`
Version: 2.1.2
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:
$krakend generate from openapi -h
╓▄█ ▄▄▌ ╓██████▄µ
▐███ ▄███╨▐███▄██H╗██████▄ ║██▌ ,▄███╨ ▄██████▄ ▓██▌█████▄ ███▀╙╙▀▀███╕
▐███▄███▀ ▐█████▀"╙▀▀"╙▀███ ║███▄███┘ ███▀""▀███ ████▀╙▀███H ███ ╙███
▐██████▌ ▐███⌐ ,▄████████M║██████▄ ║██████████M███▌ ███H ███ ,███
▐███╨▀███µ ▐███ ███▌ ,███M║███╙▀███ ███▄```▄▄` ███▌ ███H ███,,,╓▄███▀
▐███ ╙███▄▐███ ╙█████████M║██▌ ╙███▄`▀███████╨ ███▌ ███H █████████▀
`` `'`
Version: 2.1.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
-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:
$krakend generate from openapi -c ~/Downloads/openapi.yaml -o krakend.jsonThe 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:
$krakend generate from openapi -c ~/Downloads/openapi.yaml -o krakend.json -m