This page explains the support for Swagger v2 and OpenAPI v3.0.x
OpenAPI, formerly known as Swagger, is an open standard specification for defining, documenting, and designing web APIs (Application Programming Interfaces). It provides a machine-readable representation of an API, allowing developers to understand and interact with the API without the need to access its underlying implementation.
OpenAPI uses a JSON or YAML format to describe the endpoints, data models, request and response parameters, and other details of an API.
Traefik Hub supports the following versions:
- Swagger v2.0
- OpenAPI v3.0.x
Supported file formats are YAML and JSON.
It is possible to use API specs based on Swagger 2.0 with Traefik Hub.
Traefik Hub will automatically convert the spec to OpenAPI v3.0.3.
Because of the auto conversion all OpenAPI files in the Portal are OpenAPI v3.0.3.
Extensions, are custom properties that can be added to a Swagger specification to provide extra information or behavior not covered by the standard specification.
These extensions are denoted by starting with the x- prefix, for example x-logo.
Traefik Hub will try to convert Swagger extensions to OpenAPI extensions during the conversion process.
Not all Swagger extensions are supported by OpenAPI v3.x.
For example, x-example in Swagger v2 changed to example in OpenAPI v3.0.0.
That means that your converted spec will still have x-example in the source but no example will be shown in the generated file in the Portal.
Under the hood, Traefik Hub uses kin-openapi to convert Swagger v2.0 to OpenAPI v3.0.3.
If you face any problems with the conversion or if you're encountering issues with the converted spec, please get in contact with our support team.
OpenAPI specifications v3.0.x are fully supported.