Document updated on Feb 7, 2021
The OpenAPI or Swagger documentation is automatically generated by the KrakenD Enterprise binary when you use the krakend generate openapi
command.
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.endpoint
level: Defines the documentation for a specific endpoint.Both placements of the configuration are entirelly optional.
In the service level (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"
]
}
}
}
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.
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": {
"documentation/openapi": {
"description": "Very long description of what this endpoint does",
"summary": "Get my favourite foo",
"tags": ["foo", "bar", "baz"]
}
}
}
description
(string): Description of the endpoint in CommonMark or HTMLsummary
(string): A short summary for the endpointtags
(list): 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.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.
We use cookies to understand how you use our site and to improve your overall experience. By continuing to use our site, you accept our Privacy Policy. More information