Skip to main content

Swagger UI

When SwaggerEnabled is set to true for an API Proxy, Link exposes a Swagger UI endpoint that renders the OpenAPI Specification (OAS) file associated with that proxy. This provides a human-readable view of the API schema—including available endpoints, request parameters, and response structures—directly in the browser.

The following endpoints become available for the proxy at its configured Path:

EndpointDescription
/{Path}/swaggerSwagger UI — renders the API schema in a browser-friendly interface
/{Path}/swagger.jsonOpenAPI Specification — the raw OAS JSON document
/{Path}/swagger.yamlOpenAPI Specification — the raw OAS YAML document

Swagger UI showing the enosix schema document

Enabling Swagger UI​

Swagger UI is disabled by default. To enable it, set SwaggerEnabled: true in the API Proxies configuration:

ApiProxies__0__SwaggerEnabled: true

API Key Configuration​

API proxies configured with an API Key are supported by Swagger UI. When users authorize in Swagger UI using an API key, they can use the Try it out feature to execute API calls directly from Swagger UI. This enables interactive testing of the API endpoints while ensuring that only authorized users can perform such actions.

OpenID Connect (OIDC) Configuration​

API proxies configured with OpenID Auth are also supported by Swagger UI. When users authorize in Swagger UI via an OpenID Connect (OIDC) flow, they are redirected to the identity provider to sign in and then returned to Swagger UI.

If Try it out is enabled, users can execute API calls directly from Swagger UI after completing the OIDC flow.

Enabling Swagger UI Try It Out​

Swagger UI Try it out is disabled by default. To enable it, set SwaggerTryItOutEnabled: true in the API Proxies configuration:

ApiProxies__0__SwaggerTryItOutEnabled: true

Swagger UI "Try it out" example

Swagger UI supports different authentication mechanisms for testing APIs:

  1. Basic Authentication – an API proxy configured with a NoAuthentication (passthrough) destination (Basic auth is supplied by the caller). Swagger_UI
  2. API Key Authentication – an API proxy configured with an API key and a basic authentication destination. Swagger_UI
  3. Principal Propagation – an API proxy configured with a principal propagation destination. Swagger_UI
  4. API Key and Basic Authentication – an API proxy configured with a NoAuthentication (passthrough) destination and an API key (Basic auth is supplied by the caller). Swagger_UI
  5. API Key and OAuth Authentication – an API proxy configured with a principal propagation destination and an API key. Swagger_UI
  6. API Key and OIDC Authentication – an API proxy configured with OAuth, an API key, and a basic authentication destination. Swagger_UI

Multi-authentication scenarios (4 through 6 above) require an additional API proxy configuration parameter:

ApiProxies__0__SwaggerMultiAuthenticationEnabled: true

See API Proxies for the full list of configuration options.