API Portal¶

Traefik Enterprise includes an API Portal which groups all of the API specifications from your services into a web UI, if they support the OpenAPI format (formerly known as Swagger).

It works by looking for a JSON file on the service endpoint, which should match the file name defined in the configuration, and making it available on the API Portal web app. It does this for all services that expose an API specification file.

API Portal page

Configuration¶

In order to enable the API Portal, a path property must be defined in the static configuration.

API Portal Options¶

`path`¶

Required, Default=""

The path option must be a string representing the name of the specification file to look for on the service endpoint. For example, if spec.json is defined as path, the API Portal will try to get this file under the service URL. Thus, the path <service-url>/spec.json must point to the specification file.

YAML

apiportal:
  path: spec.json

TOML

[apiportal]
  path = "spec.json"

It's also possible to define the API spec path on the dynamic configuration, declared on the service definition attached to your router. Doing so overrides the path specified on the static configuration.

File (YAML)

http:
  services:
    myapi-svc:
        apiportal:
          path: /foo/spec.json

File (TOML)

[http.services.myapi-svc]
  [http.services.myapi-svc.loadbalancer]
    [http.services.myapi-svc.loadbalancer.apiportal]
      path = "/foo/spec.json"

Enabling the API Portal¶

Where is the API Portal served?

Just like the Dashboard, the API Portal is served by Ingress proxies.

An internal service called apiportal@internal serves the API Portal, which means that it's possible to use all of Traefik's routing capabilities to build the most suitable configuration.

Example¶

This example shows how to enable the API Portal on port 8888 of the domain apiportal.domain.org.

To do so, create a router through the dynamic configuration that routes all requests coming through the internal entrypoint to the apiportal@internal service. In our case, the entrypoint internal is listening to the address :8888.

First, the applied static configuration should contain the following elements:

Static Configuration (YAML)

# [...]
entrypoints:
  # [...]
  internal:
    address: ":8888"

apiportal:
  path: spec.json

Static Configuration (TOML)

# [...]
[entryPoints]
  # [...]
  [entryPoints.internal]
    address = ":8888"

[apiportal]
  path = "spec.json"

Using the teectl apply command:

Command (YAML)

teectl apply --file=static.yaml

Command (TOML)

teectl apply --file=static.toml

Then, apply the following dynamic configuration:

Docker

labels:
  - "traefik.http.routers.apiportal.rule=Host(`apiportal.domain.org`)"
  - "traefik.http.routers.apiportal.service=apiportal@internal"
  - "traefik.http.routers.apiportal.entryPoints=internal"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: apiportal
spec:
  entryPoints:
    - internal
  routes:
    - match: Host(`apiportal.domain.org`)
      kind: Rule
      services:
        - name: apiportal@internal
          kind: TraefikService

Consul Catalog

- "traefik.http.routers.apiportal.rule=Host(`apiportal.domain.org`)"
- "traefik.http.routers.apiportal.service=apiportal@internal"
- "traefik.http.routers.apiportal.entryPoints=internal"

Marathon

"labels": {
    "traefik.http.routers.apiportal.rule": "Host(`apiportal.domain.org`)",
    "traefik.http.routers.apiportal.service": "apiportal@internal",
    "traefik.http.routers.apiportal.entryPoints": "internal"
}

Rancher

labels:
  - "traefik.http.routers.apiportal.rule=Host(`apiportal.domain.org`)"
  - "traefik.http.routers.apiportal.service=apiportal@internal"
  - "traefik.http.routers.apiportal.entryPoints=internal"