Skip to main content

SwaggerUiProvider

The SwaggerUiProvider is a class that generates and provides Swagger UI documentation for your HTTP controllers. It automatically scans your controllers and their OpenAPI metadata to build a complete OpenAPI 3.1 specification and serves it through a Swagger UI interface.

Core Methods​

provide​

Registers the Swagger UI provider with the dependency injection container and builds the OpenAPI documentation from controller metadata.

provide(container: Container): void

Parameters

  • container (Container): The Inversify container instance where controllers are registered.

Notes

  • Scope: Can only be called once per provider instance. Subsequent calls will throw an error.
  • Process: Scans all registered controllers for OpenAPI metadata, builds the complete OpenAPI specification, and registers the Swagger UI controller.
  • Prerequisites: Controllers must be properly registered in the container and have appropriate OpenAPI decorators applied.

Configuration​

SwaggerUiProviderOptions​

The provider accepts configuration options that control both the API documentation and UI presentation.

interface SwaggerUiProviderOptions {
  api: SwaggerUiProviderApiOptions;
  ui?: SwaggerUiProviderUiOptions;
}

SwaggerUiProviderApiOptions​

Controls the OpenAPI specification and API endpoint configuration.

interface SwaggerUiProviderApiOptions {
  openApiObject: OpenApi3Dot1Object;
  path: string;
}

Properties

  • openApiObject (OpenApi3Dot1Object): The base OpenAPI 3.1 specification object. Controller metadata will be merged into this object.
  • path (string): The base path where the Swagger UI will be served (e.g., '/docs').

SwaggerUiProviderUiOptions​

Controls the Swagger UI presentation and customization options.

interface SwaggerUiProviderUiOptions {
  customCss?: string;
  customCssUrls?: string | string[];
  customJs?: string;
  customJsUrls?: string | string[];
  explorerEnabled?: boolean;
  swaggerUiOptions?: SwaggerUiOptions;
  title?: string;
}

Properties

  • customCss (optional string): Inline CSS to customize the Swagger UI appearance.
  • customCssUrls (optional string | string[]): External CSS stylesheet URLs to include.
  • customJs (optional string): Inline JavaScript code to execute in the Swagger UI.
  • customJsUrls (optional string | string[]): External JavaScript URLs to include.
  • explorerEnabled (optional boolean): Whether to show the API explorer input in the top bar. Defaults to false.
  • swaggerUiOptions (optional SwaggerUiOptions): Native Swagger UI configuration options.
  • title (optional string): Custom page title for the Swagger UI interface.

Internal Processing​

Metadata Collection​

The provider automatically collects metadata from your controllers including:

  • Controller base paths and OpenAPI metadata
  • Method-level route definitions and OpenAPI operations
  • Referenced schema types for request/response bodies
  • Applied middleware and guard configurations

OpenAPI Specification Building​

The provider performs several key operations:

  • Merges controller metadata into the base OpenAPI object
  • Builds path item objects for each controller method
  • Consolidates referenced schemas into the components section
  • Maps HTTP methods to OpenAPI operations
  • Resolves path parameters and request/response schemas

Controller Registration​

After building the complete OpenAPI specification, the provider:

  • Creates a framework-specific Swagger UI controller
  • Registers the controller in the dependency injection container
  • Sets up routes for serving the Swagger UI interface and static assets:
    • GET {path}: Serves the Swagger UI HTML page
    • GET {path}/spec: Serves a JSON representation of the OpenAPI spec

Error Handling​

Duplicate Operations​

The provider will throw an error if duplicate operations are detected for the same path and HTTP method combination. This typically occurs when:

  • Multiple methods in the same controller use the same route path and HTTP method
  • Controller metadata conflicts exist

Provision State​

The provider maintains internal state to prevent multiple provisioning:

  • Calling provide() more than once will throw an error
  • This ensures consistency and prevents duplicate controller registrations

Integration Requirements​

Controller Prerequisites​

Controllers must meet the following requirements for proper documentation generation:

  • Be registered in the Inversify container
  • Have appropriate OpenAPI decorators applied (from the OpenAPI decorator library)
  • Use consistent path definitions between HTTP route decorators and OpenAPI metadata