Skip to main content

SwaggerUiProvider

The SwaggerUiProvider is an abstract 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

Framework Compatibility​

The SwaggerUiProvider is an abstract class that requires framework-specific implementations. Each supported HTTP framework (Express, Fastify, Hono) has its own concrete provider implementation that handles framework-specific response handling and static file serving:

  • SwaggerUiExpressProvider from @inversifyjs/express-open-api
  • SwaggerUiExpress4Provider from @inversifyjs/express-4-open-api
  • SwaggerUiFastifyProvider from @inversifyjs/fastify-open-api
  • SwaggerUiHonoProvider from @inversifyjs/hono-open-api