@forinda/kickjs-swagger
Auto-generates an OpenAPI 3.0.3 spec from controller decorators and route schemas, and serves Swagger UI (local assets from swagger-ui-dist) and ReDoc. See the Swagger guide for the walkthrough.
Installation
pnpm add @forinda/kickjs-swaggerimport { bootstrap } from '@forinda/kickjs'
import { SwaggerAdapter } from '@forinda/kickjs-swagger'
bootstrap({
modules,
adapters: [SwaggerAdapter({ info: { title: 'My API', version: '1.0.0' }, bearerAuth: true })],
})
// GET /docs — Swagger UI, GET /redoc — ReDoc, GET /openapi.json — the specSwaggerAdapter
Application adapter that collects route metadata during mount and serves documentation endpoints.
const SwaggerAdapter: AdapterFactory<SwaggerAdapterOptions>
interface SwaggerAdapterOptions extends SwaggerOptions {
docsPath?: string // default: '/docs'
redocPath?: string // default: '/redoc'
specPath?: string // default: '/openapi.json'
adapters?: any[] // peer adapters to discover (e.g. WsAdapter)
disableInProd?: boolean // skip mounting unless NODE_ENV is 'development' or 'test'
renderSwaggerUI?: UIRenderer // swap the Swagger UI shell
renderReDoc?: UIRenderer // swap the ReDoc shell
}SwaggerAdapterOptions extends SwaggerOptions.
Marking endpoints public from route flags
publicFlag names the route flag your app already uses for open endpoints, so the spec reads the same declaration the runtime does instead of a second annotation that can drift from it:
SwaggerAdapter({ bearerAuth: true, publicFlag: 'auth.public' })
SwaggerAdapter({ bearerAuth: true, publicFlag: ['auth.public', 'health.probe'] })Resolution order per route: @ApiPublic → securityResolver() → publicFlag → @ApiSecurity / @ApiBearerAuth → global bearerAuth. The name is configuration because the framework names no flags.
For anything richer than a name — a flag's value, two flags combined — use securityResolver with getRouteFlags, which resolves method, class and mount declarations:
import { getRouteFlags } from '@forinda/kickjs'
SwaggerAdapter({
bearerAuth: true,
securityResolver: ({ controllerClass, handlerName }) =>
getRouteFlags(controllerClass, handlerName).has('auth.public') ? null : undefined,
})Because mount flags resolve here too, bootstrap({ health: { flags: ['auth.public'] } }) marks both health probes public in the spec with no extra wiring.
Built with defineAdapter() — call it as SwaggerAdapter({ … }) and pass the result to bootstrap({ adapters: [...] }). The factory wires onRouteMount (route metadata collection) and beforeMount (mount the docs UI) internally.
SchemaParser
Pluggable interface for converting validation library schemas to JSON Schema.
interface SchemaParser {
readonly name: string
supports(schema: unknown): boolean
toJsonSchema(schema: unknown, context?: { io: 'input' | 'output' }): Record<string, unknown>
}io is 'input' for request schemas and 'output' for response schemas, for libraries whose input and output shapes differ (defaults, transforms).
zodSchemaParser
The default parser (name: 'kickjs-schema'). Despite the name it is not Zod-only: it goes through @forinda/kickjs-schema, so it handles every library that package supports (Zod, Valibot, Yup, Standard Schema) and emits OpenAPI 3.0 JSON Schema.
const zodSchemaParser: SchemaParserbuildOpenAPISpec
Build a complete OpenAPI 3.0.3 spec object from all registered controllers and their decorator metadata.
function buildOpenAPISpec(options?: SwaggerOptions): anyMemoised per options object; registerControllerForDocs and clearRegisteredRoutes invalidate the cache.
registerControllerForDocs
Register a controller class for OpenAPI introspection. SwaggerAdapter calls it from onRouteMount, scoped to its own options object, so two adapters keep separate route lists.
function registerControllerForDocs(controllerClass: any, mountPath: string, scope?: object): voidclearRegisteredRoutes
Clear registered route metadata — one adapter's scope, or every scope when omitted. Called on HMR rebuild.
function clearRegisteredRoutes(scope?: object): voidDecorators
ApiOperation
Attach operation metadata (summary, description, operationId) to a route handler.
function ApiOperation(options: ApiOperationOptions): MethodDecorator
interface ApiOperationOptions {
summary?: string
description?: string
operationId?: string
deprecated?: boolean
}ApiResponse
Document a response status code. Can be stacked multiple times on the same method.
function ApiResponse(options: ApiResponseOptions): MethodDecorator
interface ApiResponseOptions {
status: number
description?: string
schema?: any
name?: string // component name under components/schemas; derived from the handler when omitted
}ApiTags
Apply OpenAPI tags at class or method level.
function ApiTags(...tags: string[]): ClassDecorator & MethodDecoratorApiBearerAuth
Mark an endpoint or controller as requiring Bearer token authentication.
function ApiBearerAuth(name?: string): ClassDecorator & MethodDecorator // name defaults to 'BearerAuth'ApiSecurity
Require a named security scheme on an endpoint or controller. Accepts a scheme name, a { name, scopes } requirement, or a list of either.
function ApiSecurity(
requirement: string | ApiSecurityRequirement | (string | ApiSecurityRequirement)[],
): ClassDecorator & MethodDecoratorA method-level requirement replaces the class-level one rather than adding to it. Reference a scheme declared in securitySchemes; only the literal name BearerAuth is auto-synthesised.
ApiPublic
Mark a single method as public — it opts out of any class-level requirement.
function ApiPublic(): MethodDecoratorMethod-only, and the highest-precedence answer in the resolution order. When the spec carries a global requirement (bearerAuth: true), the operation emits security: [], which is how OpenAPI spells "this one is open" — omitting the key would mean "inherit the global requirement".
ApiExclude
Exclude a controller or method from the generated OpenAPI spec.
function ApiExclude(): ClassDecorator & MethodDecoratorTypes
interface OpenAPIInfo {
title: string
version: string
description?: string
}
interface SecurityResolverContext {
controllerClass: any
handlerName: string
}
interface ApiSecurityRequirement {
name: string
scopes?: string[]
}
/** Renders the HTML for a docs UI — `swaggerUIHtml` and `redocHtml` implement it. */
type UIRenderer = (specUrl: string, title?: string, assetsPath?: string) => string
interface SwaggerOptions {
info?: Partial<OpenAPIInfo>
servers?: { url: string; description?: string }[]
/** Add the `BearerAuth` scheme and apply it as a GLOBAL security requirement. */
bearerAuth?: boolean
/** Route flag(s) naming a public endpoint — those routes emit `security: []`. */
publicFlag?: string | readonly string[]
/** Full control: `null` is public, `undefined` falls through, anything else sets the requirement. */
securityResolver?: (
ctx: SecurityResolverContext,
) => string | ApiSecurityRequirement | (string | ApiSecurityRequirement)[] | null | undefined
securitySchemes?: Record<string, OpenAPISecurityScheme>
/** Defaults to `zodSchemaParser`. */
schemaParser?: SchemaParser
}
/** Any OpenAPI 3 SecuritySchemeObject (`http`, `apiKey`, `oauth2`, `openIdConnect`, `mutualTLS`). */
type OpenAPISecurityScheme = Record<string, any>UI Generators
function swaggerUIHtml(specUrl: string, title = 'API Docs', assetsPath?: string): string
function redocHtml(specUrl: string, title = 'API Docs'): stringPass your own UIRenderer as renderSwaggerUI / renderReDoc to swap either shell (Scalar, RapiDoc, Stoplight Elements).