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.

Best practices for writing OpenAPI specs​

  1. Keep titles and summaries short: Use 50 characters or fewer for info.title and operation summaries. This helps reduce line wrapping and makes things easier to scan.
openapi: 3.0.3
info:
  title: "Weather API"
  version: "1.0"
paths:
  /forecast:
    get:
      summary: Get weather forecast
      description: "Returns weather forecast for a location."
      responses:
        '200':
          description: "OK"
  1. Add operation IDs: Assign each operation a unique, code-friendly operationId that can be referenced by client libraries or used for linking.
paths:
  /forecast:
    get:
      operationId: getForecast
      summary: "Get weather forecast"
      responses:
        '200':
          description: "OK"
  1. Provide examples: Add meaningful request and response examples (using example or examples) so developers can quickly understand data formats.
paths:
  /forecast:
    get:
      responses:
        '200':
          description: "Success"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Forecast"
              example:
                - location: "London"
                  temperature: 18
                  conditions: "Cloudy"
                - location: "Paris"
                  temperature: 22
                  conditions: "Sunny"

components:
  schemas:
    Forecast:
      type: object
      properties:
        location:
          type: string
          example: "London"
        temperature:
          type: integer
          example: 18
        conditions:
          type: string
          example: "Cloudy"
  1. Use security schemes: Include at least one security scheme (e.g., OAuth2, API key). Reference it globally or at the operation level.
openapi: 3.0.3
info:
  title: "Weather API"
  version: "1.0"
security:
  - weather_auth:
      - read:forecast
      - read:alerts
components:
  securitySchemes:
    weather_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://example.com/oauth/authorize
          scopes:
            read:forecast: "Access weather forecasts"
            read:alerts: "Access weather alerts"
  1. Describe your components: Add brief description fields for key elements (paths, parameters, schemas, etc.). This helps others understand usage quickly.
components:
  schemas:
    Forecast:
      type: object
      description: "Represents weather forecast data."
      properties:
        location:
          type: string
          description: "City or location name."
        temperature:
          type: integer
          description: "Temperature in Celsius."
  1. Avoid inline schemas: Use $ref to point to schemas defined under components/schemas instead of embedding them directly in request/response bodies.
paths:
  /forecast:
    get:
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Forecast"
  1. Include Tags: Group related operations under tags. This helps organize large APIs and makes it easier to find operations in the API Portal.
paths:
  /alerts:
    get:
      tags:
        - Weather
      summary: Get weather alerts
      operationId: getAlerts
      responses:
        '200':
          description: "Alerts retrieved"
  1. Keep consistent naming: Pick one style (e.g., camelCase) for parameters, properties, and schema names throughout your spec to avoid confusion.
paths:
  /forecast:
    get:
      operationId: getForecast
      parameters:
        - name: locationId
          in: query
          schema:
            type: string
  1. Add contact info: Provide a contact section in info, so consumers know who to reach if they have questions or issues.
info:
  title: "Weather API"
  version: "1.0"
  contact:
    name: "Weather Support Team"
    email: "[email protected]"
  1. Enhance your OpenAPI for LLM-based tools: If you plan to use an AI assistant, consider making your OpenAPI spec as descriptive and consistent as possible:
  • Rich descriptions: Provide clear description fields for paths, parameters, and schemas. More context helps the AI produce accurate examples and documentation.
  • Valid & complete spec: Ensure your spec is valid OpenAPI, with consistent schema references. Some AI tools struggle with partial or wrong specs.
  • Detailed examples: Include example requests and responses (via example or examples) so the AI can demonstrate realistic calls and data formats.
  • Single consolidated file: Many LLM-based tools prefer a single OpenAPI file. If your spec is split into multiple files, consider merging them or using a single file for AI consumption.
  • Consistent naming: Keep parameter and schema naming patterns coherent (e.g., camelCase). AI-based tools often rely on these cues for code generation.