Skip to main content

Swagger UI Support

Overview​

K5 SDK enables Swagger UI generation for API namespaces modelled in Solution Designer. This feature provides an interactive API documentation interface for all API namespaces' endpoints, making it easy to explore and test API requests directly from the browser, see also API Modelling.

ℹ️note

Swagger UI Support is controlled via the project configuration file k5-project.yml

Accessing Swagger UI​

For local development, Swagger UI is typically available at:

http://localhost:3000/swagger-ui/index.html

This interface allows developers to visualize API operations, view request/response schemas, and interact with the API endpoints.

OAuth2 Authentication Support​

Swagger UI supports OAuth2 authentication, allowing developers to test endpoints that require authentication. To enable this feature, certain environment variables need to be configured in your .env file.

Example .env Configuration​

# URL to OIDC issuer which is responsible for authentication of REST API
OIDC_ISSUER_URI=<oidc-issuer-uri>
# Swagger UI client id
SWAGGER_UI_CLIENT_ID=<swagger-ui-client-id>

Authentication Workflow​

  1. Set up the above environment variables in your .env file.
  2. Restart your application to apply the changes.
  3. Navigate to Swagger UI and click the Authorize button.
  4. Enter the required authentication details.
  5. Once authenticated, you can make authorized API requests directly from Swagger UI.

Swagger UI authorization

Helmet Protection Customization​

Enabling the swaggerUISupport extension also interacts with Helmet protection. This appends the Helmet security options only for Swagger UI routes to allow inline swagger-ui redirect logic scripts to be run correctly, as well as crossOriginOpenerPolicy so that the oidc auth callback can redirect successfully to swagger-ui.

This customization is necessary for Swagger UI OAuth2 authentication redirects to work correctly. Without it, default helmet security policies may block the redirect flow. For more details, see the related issue in swagger-ui.

The customized Helmet options for Swagger UI include:

const swaggerHelmetOptions: HelmetOptions = {
  ...helmetOptions,
  contentSecurityPolicy: {
    directives: {
      ...helmet.contentSecurityPolicy.getDefaultDirectives(),
      'script-src': [
        "'self'",
        "'sha256-4IiDsMH+GkJlxivIDNfi6qk0O5HPtzyvNwVT3Wt8TIw='",
        "'sha256-tScXhlIZQ224nNd7mZP0sX4vmjFCv2kMVzsFdWDi7zg='",
      ],
      'connect-src': ["'self'"],
    },
  },
  crossOriginOpenerPolicy: { policy: 'unsafe-none' },
};