Skip to content

OpenAPI

This page explains the support for Swagger v2 and OpenAPI v3.0.x

Logos of Swagger and OpenAPI Initiative

Introduction

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.

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.

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.

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.

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.

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

OpenAPI v3.0.x

OpenAPI specifications v3.0.x are fully supported.