Generate documentation using OpenAPI

Document updated on May 7, 2021

The OpenAPI or Swagger generator is a command line utility embedded in the KrakenD binary, offering the automatic generation of API documentation through a static Swagger file.

For an OpenAPI specification with detailed fields of backend responses (an information the gateway does not have), use the OpenAPI generator in the KrakenD Studio as is capable of providing in-depth detail of backend responses in the documentation through inspection of live requests.

The swagger output can be saved statically and served to end-users once is generated. A good place to generate the specs is in your CI/CD pipeline.

Generating the 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: v1.3.0
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")

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.

OpenAPI configuration

The following piece of configuration in your KrakenD configuration enables a richer generation of the swagger file:

{
  "version": 2,
  "name": "Your KrakenD API",
  "extra_config": {
    "github_com/devopsfaith/krakend-swagger": {
        "description": "This is a sample server. You can find out more about at [http://blah](http://blah.blah.com)",
        "version": "1.0.0",
        "host": "my.api.com",
        "basePath": "/v1",
        "termsOfService": "http://url.to/tos",
        "contact-name": "The wonderful API department",
        "contact-email": "[email protected]",
        "contact-url": "https://your.company/developers",
        "license-name": "MIT",
        "license-url": "https://opensource.org/licenses/MIT",
        "tags": ["B2B", "Restricted"]

    }
  }
}

The fields shown above are business information that you can fill (or not) as per your needs. These fields are metadata giving context about your company and how to get in touch with you as an end-user. Swagger will use as the title of your API the value of name in the root configuration (outside the component). In case there is no name, the string KrakenD - API Gateway is the default.

Documenting endpoints

In addition to setting global metadata for the whole API you can insert additional information to each endpoint, so users can have an explanation of what the endpoint does:

{
     "endpoint": "/foo",
     "extra_config": {
        "github_com/devopsfaith/krakend-swagger": {
            "description": "Very long description of what this endpoint does",
            "summary": "Get my favourite foo",
            "tags": ["foo", "bar", "baz"]
        }
      }
}