News KrakenD CE v2.8 released with improved Lua and OpenTelemetry

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

Document updated on Oct 25, 2022

OpenAPI/Swagger Generation

The OpenAPI documentation (formerly Swagger) is automatically generated by the KrakenD Enterprise binary when you use the krakend openapi export command (see Exporting to OpenAPI).

OpenAPI configuration

The OpenAPI documentation configuration has two different placements that you can use:

  • service level: Defines the general business information and metadata that provides context about your company and how to get in touch with you as an end-user, it is common to all endpoints.
  • endpoint level: Defines the documentation and metadata for a specific endpoint.

Both configuration placements are optional, and when you don’t provide the information, KrakenD sets defaults.

Setting the basic API information

At the service level (the root of the configuration file), you can declare an extra_config with the documentation/openapi to declare the general API information for your developers. All the fields are optional.

The available fields are self-explanatory by seeing the following example:

{
  "version": 3,
  "name": "Your KrakenD API",
  "extra_config": {
    "documentation/openapi": {
        "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",
        "base_path": "/v1",
        "terms_of_service": "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"],
        "schemes": [
          "http",
          "https"
        ]
    }
  }
}
Fields of "documentation/openapi"
* required fields

base_path string
A starting path that is appended to any endpoint.
Example: "/v1"
contact_email string
Email where users of your API can write to.
Example: "/v1"
contact_name string
Contact name.
Example: "/v1"
contact_url string
Contact URL that users of your API can read.
Example: "/v1"
description string
An introductory, optionally verbose, explanation supporting CommonMark syntax. If you’d like to load an external markdown file, you can use flexible configuration, for instance "description": {{include "openapi/intro.md" | toJson }}
Example: "Hi there, I am [OpenAPI](https://www.krakend.io/docs/enterprise/endpoints/openapi/)"
host string
The hostname where you will publish your API.
Example: "my.api.com"
license_name string
The license name (e.g.: Apache License)
Example: "/v1"
license_url string
The URL where the license is hosted
Example: "/v1"
schemes array
The list of schemes supported by the API, e.g. http or https
Example: ["https","http"]
Defaults to ["http"]
tags array
You can assign a list of tags to each API operation. Tagged operations may be handled differently by tools and libraries. For example, Swagger UI uses tags to group the displayed operations.
terms_of_service string
The URL to the terms of service for using this API.
Example: "/v1"
version string
The version numbering you want to apply to this release of API., e.g.: 1.0.
Example: "1.0"

The name specified in the root of the configuration (outside the OpenAPI’s extra_config) is used as the title of your API. If none is present, the string KrakenD - API Gateway is the default.

If you want to include a full markdown file in the introduction, you can use flexible configuration to ease this process. For instance, if you write a markdown file, under partials/openapi/intro.md you can load it automatically as follows:

{
  "version": 3,
  "name": "Your KrakenD API",
  "extra_config": {
    "documentation/openapi": {
      "description": {{include "openapi/intro.md" | toJson }},
    }
  }
}

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 every endpoint does. All fields are optional:

{
     "endpoint": "/foo",
     "extra_config": {
        "documentation/openapi": {
            "description": "Very long description of what this endpoint does",
            "summary": "Get my favourite foo",
            "tags": ["foo", "bar", "baz"],
            "audience": ["gold","silver","bronze"],
            "example": {
              "user_id": 33
            }
        }
      }
}
Fields of "documentation/openapi"
* required fields

audience array
The list of audiences that will consume this endpoint. These values do not define the gateway logic in any way. They are a way to group endpoints and filter them out when generating the OpenAPI documentation. Use * to indicate an endpoint will be present in any audience generated.
Example: ["gold","silver","*"]
description string
An introductory, optionally verbose, explanation supporting CommonMark syntax. If you’d like to load an external markdown file, you can use flexible configuration, for instance "description": {{include "openapi/intro.md" | toJson }}
Example: "Hi there, I am [OpenAPI](https://www.krakend.io/docs/enterprise/endpoints/openapi/)"
example object, string
Deprecated in OAS3 (use response_definition instead). A free form JSON object or a string you would like to show as a sample response of the endpoint. The examples assume they are JSON content types except when using the output_encoding=string.
response_definition object
Describes the different status codes returned by this endpoint. Each key is the definition of the status code, represented by a string. E.g., 200 (success), 500 (internal error), etc.
Example: {"404":{"@comment":"Some comment","content_type":"application/json","description":"Page not found","example":{"status":"KO"}}}

Properties of response_definition can use a name matching the pattern ^[0-9]+$, and their content is an object with the following properties:

content_type string
The content type returned by this error, e.g., application/json
description string
The description of this error code, e.g., Page not found.
example string, object, array, boolean, integer, null, number
A free form JSON object or a string you would like to show as a sample response of the endpoint. The examples assume they are JSON content types except when using the output_encoding=string.
example_schema string
A JSON schema that describes the response format for the selected status code, encoded as a base64 string. Use either example or example_schema, but not both.
summary string
A short summary for the endpoint. Use the description field for the longest explanation.
tags array
You can assign a list of tags to each API operation. Tagged operations may be handled differently by tools and libraries. For example, Swagger UI uses tags to group the displayed operations.

Integration with JSON Schema

When your endpoint uses a validation/json-schema, all write methods (POST, PUT, PATCH, DELETE) add in the documentation automatically its validation conditions.

Define different audiences of your OpenAPI

When you declare your endpoints, you might want to restrict some of them from appearing in the final documentation export because the audience consuming them doesn’t need to be aware of their existence.

For instance, let’s say your API exposes endpoints like /user, /cart, or /admin, where the administration endpoint is for internal usage. Why would you document it for your end-users if they are not supposed to use it or know its existence?

For cases like this, you might want to add definitions of specific audiences to the endpoints. For instance:

[
  {
    "endpoint": "/user",
    "extra_config": {
      "documentation/openapi": {
        "description": "The user endppoint",
        "audience": [
          "public",
          "internal"
        ]
      }
    }
  },
  {
    "endpoint": "/cart",
    "extra_config": {
      "documentation/openapi": {
        "description": "The cart endpoint",
        "audience": [
          "public",
          "internal"
        ]
      }
    }
  },
  {
    "endpoint": "/admin",
    "extra_config": {
      "documentation/openapi": {
        "description": "The admin endpoint",
        "audience": [
          "internal"
        ]
      }
    }
  },
  {
    "endpoint": "/no-audience",
    "extra_config": {
      "documentation/openapi": {
        "description": "The admin endpoint"
      }
    }
  }
]

Then, when generating the documentation, you can filter out the /admin endpoint and exclude it from the final documentation with krakend openapi export -c krakend.json -a public. The command would document /user, /cart, and /no-audience.

It is important to notice that when you filter by audience, all endpoints without defining one, will appear in the final documentation.

Similarly, using krakend openapi export -c krakend.json -a internal would generate the documentation for all the endpoints, but not specifying the -a flag would have produced the same effect.

Notice that the audience attribute lets you exclude endpoints from the final documentation, but they exist anyway in the service, and you must protect them against unwanted usage.

Documenting response examples and errors

The response_definition object allows you to set examples of the response an API endpoint will deliver. For instance:

{
  "endpoint": "/cart",
  "extra_config": {
    "documentation/openapi": {
      "description": "The cart endpoint",
      "response_definition": {
        "200": {
          "example": {
            "status": "OK",
            "message": "Product added to the cart!"
          }
        },
        "500": {
          "example": {
            "status": "KO",
            "message": "Couldn't add the product to the cart!"
          }
        }
      }
    }
  }
}

When the examples are long, you might want to have the example responses in a separate file (like settings or partial) using Flexible Configuration, so the endpoint template keeps being readable. For instance

{
  "endpoint": "/cart",
  "extra_config": {
    "documentation/openapi": {
      "description": "The cart endpoint",
      "response_definition": {
        "200": {
          "example": {{- include openapi_cart_response.json -}}
        }
      }
    }
  }
}

You can also use define an example using the example_schema (schema takes precedence), in base64. There are different ways you can alliviate the burden of writing code in base64. For instance:

{
  "endpoint": "/cart",
  "extra_config": {
    "documentation/openapi": {
      "description": "The cart endpoint",
      "response_definition": {
        "200": {
          "example_schema": {{- include cart_schema.json | b64enc -}}
        }
      }
    }
  }
}

Or writing the schema inline, escaped with backticks:

{
  "endpoint": "/cart",
  "extra_config": {
    "documentation/openapi": {
      "description": "The cart endpoint",
      "response_definition": {
        "200": {
          "example_schema":: "{{ `{
          "type": "object",
          "title": "This is the response"
          }` | b64enc }}"
        }
      }
    }
  }
}
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.

See all support channels