function OpenApiPlugin
Since 0.1.0
OpenApiPlugin(options?: OpenApiPluginOptions): IPlugin

Creates an OpenAPI plugin that auto-generates OpenAPI 3.1 documentation from registered routes and serves it (with optional Swagger UI).

The plugin:

  • Registers an IOpenApiService under CAPABILITIES.OPENAPI
  • Drains CAPABILITIES.OPENAPI_SCHEMA contributions at registration
  • Serves the spec at specEndpoint (default /openapi.json)
  • Serves Swagger UI at endpoint (default /docs) when swagger !== false
  • Omits its own two endpoints from the document, plus anything named in OpenApiGeneratorOptions.exclude

Declaring securitySchemes is what gives Swagger UI its Authorize button. Pair it with security to state that operations require authentication by default; an individual route opts out with schema: { security: [] }.

Examples

Example 1

app.register(OpenApiPlugin({
  title: 'My API',
  version: '1.0.0',
  endpoint: '/docs',
  specEndpoint: '/openapi.json',
  securitySchemes: {
    bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
  },
  security: [{ bearerAuth: [] }],
  exclude: ['/health', '/live', '/ready', '/metrics'],
}));

Parameters

optional
options: OpenApiPluginOptions

Plugin options

Return Type

IPlugin

An IPlugin instance

Usage

import { OpenApiPlugin } from "openapi-plugin/src/index.ts";