Document updated on Oct 25, 2022
The OpenAPI or Swagger documentation is automatically generated by the KrakenD Enterprise binary when you use the krakend generate openapi
command (see Exporting to OpenAPI).
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.
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"
]
}
}
}
| A starting path that is appended to any endpoint. Example: "/v1" |
| Email where users of your API can write to. Example: "/v1" |
| Contact name. Example: "/v1" |
| Contact URL that users of your API can read. Example: "/v1" |
| Description in CommonMark or HTML. Example: "This is a sample server. You can find out more about at [http://blah](http://blah.blah.com)" |
| The hostname where you will publish your API. Example: "my.api.com" |
| The license name (e.g.: Apache License) Example: "/v1" |
| The URL where the license is hosted Example: "/v1" |
| The list of schemes supported by the API, e.g. http or https Example: ["https","http"] Defaults to ["http"] |
| 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 URL to the terms of service for using this API. Example: "/v1" |
| The version numbering you want to apply to this release of API., e.g.: 1.0 .Example: "1.0" |
Schema: https://www.krakend.io/schema/v2.1/documentation/openapi.json
* indicates a required field.
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 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
}
}
}
}
| 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. Example: ["gold","silver"] |
| Description in CommonMark or HTML. Example: "This is a sample server. You can find out more about at [http://blah](http://blah.blah.com)" |
| 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 . |
| A short summary for the endpoint. |
| 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. |
Schema: https://www.krakend.io/schema/v2.1/documentation/openapi.json
* indicates a required field.
When your endpoint uses a validation/json-schema
, all write methods (POST
, PUT
, PATCH
, DELETE
) add in the documentation automatically its validation conditions.
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"
]
}
}
}
]
Then, when generating the documentation, you can filter out the /admin
endpoint and exclude it from the final documentation with krakend generate openapi -c krakend.json -a public
.
Similarly, using krakend generate openapi -c krakend.json -a internal
would generate the documentation for the three 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, and you must protect them against unwanted usage.
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