Skip to main content

OpenAPI

Traefik Hub supports Swagger v2 and OpenAPI v3.0.x.


Introduction

OpenAPI, formerly known as Swagger, is an open standard specification for defining, documenting, and designing web APIs.

OpenAPI uses a JSON or YAML format to describe the endpoints, data models, request and response parameters, and other details of an API.


Supported Versions

Traefik Hub supports the following versions:

  • Swagger v2.0
  • OpenAPI v3.0.x

Supported file formats are YAML and JSON.


Swagger v2

It is possible to use API specs based on Swagger 2.0 with Traefik Hub.

info

Traefik Hub will automatically convert the specification to OpenAPI v3.0.3.

Because of the auto conversion, all OpenAPI files in the Portal are OpenAPI v3.0.3.

Swagger Extensions

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.

Good to know

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, but example will be shown in the generated file in the Portal.

Conversion

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 specification, please get in contact with our support team.