News KrakenD CE v2.7 released with better rate-limiting and security options

Enterprise Documentation

Recent changes

You are viewing a previous version of KrakenD Enterprise Edition (v2.5) , go to the latest version

Generating API documentation

Document updated on Nov 29, 2023

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.5 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.5 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.

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

The Dockerfile could look like this:

FROM krakend/krakend-ee:2.5 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"
# The flexible_config.json has an "out" pointing to /tmp/krakend.json
RUN krakend openapi export -c /tmp/krakend.json -o /tmp/swagger.json


# Swagger UI download
FROM alpine as swagger
# Clone the Swagger UI
RUN apk add git
RUN git clone https://github.com/swagger-api/swagger-ui.git
# Replace the demo URL with yours: /docs/
RUN sed -i "s@https://petstore.swagger.io/v2/@/docs/@" swagger-ui/dist/swagger-initializer.js
RUN mv swagger-ui/dist /docs


# Final clean image
FROM krakend/krakend-ee:2.5 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=swagger /docs /etc/krakend/docs/
COPY --from=builder /tmp/swagger.json /etc/krakend/docs/swagger.json
Scarf

Unresolved issues?

The documentation is only a piece of the help you can get! Whether you are looking for Open Source or Enterprise support, see more support channels that can help you.