Document updated on May 29, 2023

Import and Export OpenAPI definitions

The OpenAPI integration is a series of commands embedded in the KrakenD binary and additional metadata you can add in the configuration to enrich the documentation.

KrakenD offers OpenAPI import and export capabilities for OAS3 and Swagger v2 (--legacy mode), so you can autogenerate documentation or create a gateway configuration from one or multiple OpenAPI specs.

The openapi command supports the following functionalities:

• openapi export: Creates OpenAPI documentation by reading the KrakenD configuration.
• openapi import: Creates a KrakenD configuration from OpenAPI specification files.
• openapi serve: Starts a KrakenD server and an OpenAPI UI by reading the specification of an OpenAPI document (import+run).

Exporting to OpenAPI

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

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

Version: 2.10.3

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

Usage:
  krakend openapi export [flags]

Examples:
krakend openapi export --audience audience --config config.json --out openapi.json

Flags:
  -a, --audience string   Filter out endpoints not matching the given 'audience'.
  -c, --config string     Path to a KrakenD configuration file.
  -h, --help              help for export
  -L, --legacy            Use old Swagger v2
  -o, --out string        Path to the generated result. (default "out.json")

The critical flags are --config, pointing to your krakend.json file, and --out as the final output OpenAPI file in JSON format. If you use Flexible Configuration, you need to pass as --config the file delivered by 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. The metadata allows you to write user-friendly documentation in the configuration that will be rendered on the final OpenAPI document.

Filtering which endpoints are documented

Sometimes you don’t want to document all the existing endpoints in the gateway but only a subset. Using the --audience flag, you can filter which endpoints appear in the documentation during the generation. This flag selects the audiences as defined 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 specific endpoints intended for internal usage only to final customers?

Adding OpenAPI documentation in the CI/CD process

You can add the OpenAPI generation command to your existing build pipeline. You can save the OpenAPI output somewhere else or 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 openapi export -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 one ore more existing OpenAPI files, then the command you need to use is krakend openapi import:

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

Version: 2.10.3

Generates a KrakenD configuration from your OpenAPI specification.

Usage:
  krakend openapi import [flags]

Examples:
krakend openapi import --spec openapi.(json|yaml) --out krakend.json --mock false --lint true

Flags:
  -b, --base-config string   Path to a base KrakenD configuration file to extend with the OpenAPI specifications
  -h, --help                 help for import
  -L, --legacy               Use old Swagger v2
  -l, --lint                 Lint the generated configuration.
  -m, --mock                 Creates an API with autogenerated mocked responses.
  -o, --out string           Path to the generated result. (default "out.json")
  -s, --spec string          Path to an OpenAPI specification file.
  -d, --spec-dir string      Path to a directory where OpenAPI spec files are stored. (--legacy/-L not supported)

The --spec 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 openapi import -s openapi.yaml -o krakend.json

If you have more than one OpenAPI file you’d like to import and merge in a final configuration, pass a directory full of OpenAPI specs in YAML or JSON formats. For instance:

$krakend openapi import -d dir_with_openapis/ -o krakend.json

When you generate the configuration, KrakenD includes the following:

• All the endpoints declared in the files with no-op encoding (reverse proxy). Of course, 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 the host defined in the first OpenAPI directory (alphabetically) or an empty host if not defined, 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, except if you use Swagger v2 format with the flag --legacy:

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

The base configuration

When using the -b or --base-config whether you are doing one import, or loading a whole directory of OpenAPI specs, the file passed in this flag is used as the base configuration for the final configuration file.

You can set here any global settings like telemetry, logging, the listening port, the configuration name, the default host, or a few endpoints in addition to the imported specs.

Both the base configuration and the imported OpenAPI files merge together in the final render.

$krakend openapi import -d dir_with_openapis/ -o krakend.json -b base_krakend.json

The base_krakend.json file could look like this:

{
  "version": 3,
  "name": "Master configuration",
  "extra_config": {
    "telemetry/logging": {
      "level": "DEBUG",
      "prefix": "[KRAKEND]",
      "stdout": true,
      "syslog": false
    },
    "endpoints": [
      {
        "endpoint": "/health",
        "backend": [
          {
            "url_pattern": "/infra/health"
          }
        ]
      }
    ]
  }
}

x-krakend metadata

In addition to the base configuration file, you can add KrakenD metadata to your OpenAPI files, which is used to generate the configuration.

The OpenAPI spec is designed to document APIs as a consumer, but if you want to configure a gateway from an OpenAPI, you will need a lot more information that is irrelevant to the OpenAPI spec (the consumer). For instance, let’s say that you want to add a service rate limit to KrakenD every time you import from an OpenAPI file, or that you need to change the upstream service for a specific consumer path. In cases like this, the consumer still needs to use the same host, but the gateway won’t!

In scenarios like this, you can add x-krakend- (in lowercase) plus the KrakenD configuration attributes you want to set. For instance, the following OpenAPI specification adds an input_headers and the full backend definition to the path /pets:

{
  "paths": {
    "/pets": {
      "get": {
        "x-krakend-input_headers": [ "Authorization" ],
        "x-krakend-backend": [
          {
            "method": "POST",
            "url_pattern": "/shop/pet"
          }
        ],
        "summary": "List all pets",
        "operationId": "listPets"
      }
    }
  }
}

The metadata attributes are accepted for service-level attributes and endpoints.

Notice that you only set the x-krakend- key for the attribute you want to define, and anything nested after that level does not need the x-krakend- prefix.

You can combine the usage of this metadata with a base configuration and the x-krakend metadata. Be aware that if you define the same keys, the metadata overwrites any existing keys in the base configuration.

Multiple OpenAPI file import and merging

Suppose several teams generate their OpenAPI specs, and you want to merge all contracts in a single endpoints array. Then, when passing multiple OpenAPI specs during the import, KrakenD merges all the endpoints from the included specifications at once.

If there are repeated endpoints in different files, KrakenD will load them all in the final configuration, and you will need to manually resolve the conflict.

$krakend openapi import -d dir_with_openapis/ -o krakend.json

Mock data

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 openapi import -s ~/Downloads/openapi.yaml -o krakend.json -m

Serve an OpenAPI spec

The openapi serve command receives the OpenAPI file you want to start as input and starts a KrakenD server with its defined endpoints. In addition, it also serves a Swagger UI in an additional port (defaults to 15000).

For instance, by executing the following:

$krakend openapi serve -s ~/Downloads/openapi.yaml -o krakend.json -m

You would have your API on port localhost:8080 (unless the configuration changes it) and the UI on localhost:15000. The -m flag is helpful when your backend does not exist yet, and you want to return mocked data by KrakenD itself.

The -o flag will write the configuration file KrakenD has started in the disk, but it’s not required for the operation, only for you to see the final result.

You can change the host and the UI port by passing the appropriate flags. For instance:

$krakend openapi serve -s ~/Downloads/openapi.yaml -p 18000 -m

When using Docker, remember to expose the OpenAPI UI port if you want to have access from the outside.

The UI is open to anyone with access to the machine, and it needs OpenAPI version 3.

Migration from older versions

The commands krakend generate openapi and krakend generate from openapi used in previous versions keep working in v2.3 as they did in previous versions. Still, they will be removed in the future.

These commands are now replaced by krakend openapi export and krakend openapi import, which default now to OpenAPI 3 instead of Swagger v2. The new commands also support swagger, but you must add the --legacy flag.

These are the changes you need in the code.

Migration from old export

Diff for OpenAPI3 users:

- krakend generate openapi -c krakend.json -o openapi.json --oas3
+ krakend openapi export -c krakend.json -o openapi.json

Diff for Swagger v2 users:

- krakend generate openapi -c krakend.json -o openapi.json
+ krakend openapi export -c krakend.json -o openapi.json --legacy

Migration from old import

Diff for OpenAPI3 users:

- krakend generate from openapi -c openapi.json -o krakend.json --oas3
+ krakend openapi import -s openapi.json -o krakend.json

Diff for Swagger v2 users:

- krakend generate from openapi -c openapi.json -o krakend.json
+ krakend openapi import -s openapi.json -o krakend.json --legacy