OpenAPI/Swagger Generation

Document updated on Feb 7, 2021

The OpenAPI or Swagger generator is a component provided by the KrakenD Studio, offering the automatic generation of API documentation through a static Swagger file. Even KrakenD is the gateway and lacks all the knowledge of your API backends, KrakenD Studio is capable of providing in-depth detail of backend responses in the documentation documentation:inspection of live requests.

Generating the OpenAPI spec

When you run the KrakenD configuration through KrakenD Studio you can enable the Swagger generation from the UI, or by adding the configuration snippet in your krakend.json. When you push a swagger-enabled configuration, Studio automatically creates the Swagger documentation with all the defined endpoints. This initial scan contains only the endpoint definition as found on the KrakenD file, lacking the low level detail of backend payloads.

After this point KrakenD Studio starts an inspection session where the live responses from backends are captured and used to populate even more the documentation. The documentation in the /swagger.json endpoint (modifiable) is refreshed each timespan you have set with the accumulated changes in-memory. The percentatge of intercepted requests and how often you want the swagger to update is configurable.

The swagger output can be saved statically and served to end-users (including from KrakenD EE itself), but the population of its content is meant to be done while in development through Studio only.

OpenAPI configuration

The following piece of configuration in your KrakenD configuration enables the generation of the swagger file. The configuration below can be used in production as only the KrakenD Studio knows how to use it. You don’t need to remove this block when deploying, it will simply be ignored by KrakenD API Gateway.

{
  "version": 2,
  "name": "Your KrakenD API",
  "extra_config": {
    "github_com/devopsfaith/krakend-swagger": {

        "fraction": 1,
        "refresh": "60s",
        "path": "/swagger.json",

        "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 configuration above has two different blocks which we have separated on purpose using a couple of linebreaks.

The first block are parameters meant to configure the OpenAPI generation, and are:

• fraction: A float64 number between 0 and 1 representing the percentage of requests being inspected to generate the documentation. Example: 0.1 = 10% of all requests. Devault value is 0 (do not inspect requests).
• path: Endpoint path where the swagger JSON file is published. Defaults to /swagger.json if the attribute is missing.
• refresh: The amount of time passed until the swagger.json is updated with the collected activity. Default is every minute (60s)

The second block is 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"]
        }
      }
}