Document updated on Nov 29, 2023
Generating API documentation
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.
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 theopenapi export
command - Build the UI automatically using the specification
- Optionally add a route in KrakenD to serve the generated documentation
Automatic documentation with Redocly
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
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