Generating API documentation

Document updated on Nov 29, 2023

Only applies to KrakenD Enterprise

About this feature

Since	v2.0
Source	krakend/krakend-schema

Table of contents

KrakenD supports exporting (and importing) OpenAPI Specification. This flexibility allows you to auto-generate documentation that you can serve from the gateway itself, or host somewhere else.

There are multiple ways of generating docs

API documentation is a dragon of many heads. This page sets an example for you to understand how to do it, and open the door to start working with it. It does not mean that you have to generate the docs on the Docker image, or that you need to serve the documentation from KrakenD itself.

You can see a working example with a few more options, like creating an intro in markdown, or define requests and responses in the examples repository.

The idea of the auto-generation is that after every commit or release, you:

Export your gateway configuration to an openapi.json file with the openapi export command
Build the UI automatically using the specification
Optionally add a route in KrakenD to serve the generated documentation

Automatic documentation with Redocly

Screenshot of Redocly auto-generated documentation The following example generates the documentation using Redocly during the Docker build process. The steps are:

It copies the configuration to /etc/krakend
Runs the openapi export command
Runs the Redocly CLI which generates the documentation from the OpenAPI spec.
Generates a clean KrakenD image with the configuration and the documentation

The Dockerfile could look like this:

FROM krakend/krakend-ee:2.6 AS builder

# This is an Enterprise feature, make sure to have the LICENSE in the krakend dir
COPY krakend /etc/krakend

RUN FC_DEBUG=true krakend check -d -t -c "krakend.json"
RUN krakend openapi export -c /tmp/krakend.json -o /tmp/openapi.json

# Redocly generation
FROM redocly/cli as redocly
COPY --from=builder /tmp/openapi.json /spec/swagger.json
# Outputs under /spec/redoc-static.html
RUN /usr/local/bin/redocly build-docs swagger.json

FROM krakend/krakend-ee:2.6 AS production
COPY krakend/LICENSE /etc/krakend/LICENSE
# Copy the final configuration and the documentation
# which will be served from KrakenD itself under /docs/
COPY --from=builder /tmp/krakend.json /etc/krakend/krakend.json
COPY --from=redocly /spec/redoc-static.html /etc/krakend/docs/index.html

And the paths used assume that you want to serve the documentation under /docs/, so you would need an endpoint definition like the following:

{
    "@comment": "This endpoint serves the documentation under /docs/",
    "endpoint": "/docs/*",
    "output_encoding": "no-op",
    "backend": [
        {
            "extra_config": {
                "backend/static-filesystem": {
                    "path": "./docs/"
                }
            },
            "url_pattern": "/",
            "host": [
                "http://leave-this-value"
            ]
        }
    ]
}

Explore the Redocly options for an even richer documentation.

Download example

Automatic documentation with Swagger UI

Screenshot of SwaggerUI auto-generated documentation The well known Swagger UI could also be generated simlary. The following example has these steps:

It copies the configuration to /etc/krakend
Runs the openapi export command
Clones the plain HTML Swagger UI
Replaces the default swagger URL (there are much better ways to do this) with a sed.
Generates a clean KrakenD image with the configuration and the documentation