Swagger Reference (exisjs/swagger)
The exisjs/swagger module provides tools and decorators for auto-generating OpenAPI 3.1 specifications and serving interactive documentation UIs.
import { swagger, defineSwagger, generateOpenApiSpec, renderDocumentationHtml, mountDocumentation, ApiTags, ApiOperation, ApiResponse, ApiBearerAuth, ApiSecurity, ApiExclude, ApiProperty,} from 'exisjs/swagger'Configuration (SwaggerConfig)
| Property | Type | Default | Description |
|---|---|---|---|
enabled | boolean | false | Whether to enable documentation routes |
path | string | '/docs' | URL path for the interactive HTML UI |
specPath | string | '/docs/json' | URL path for OpenAPI 3.1 JSON specification |
title | string | 'ExisJS API Documentation' | API Title displayed in documentation |
version | string | '1.0.0' | API Version string |
description | string | undefined | Overview markdown or description |
ui | 'swagger-ui' | 'scalar' | 'swagger-ui' | Documentation UI renderer |
servers | OpenApiServer[] | [{ url: '/' }] | Target server list |
tags | OpenApiTag[] | [] | Group tags with descriptions |
security | Record<string, string[]>[] | [] | Global security requirements |
securitySchemes | Record<string, SecurityScheme> | {} | Reusable security scheme definitions |
customCss | string | undefined | Custom CSS injected into the UI |
customFavicon | string | undefined | Custom favicon image URL |
transformSpec | (spec: OpenApiSpec) => OpenApiSpec | undefined | Hook to mutate OpenAPI spec before serving |
Decorators
@ApiTags(...tags: string[])
Assigns one or more tags to a controller class or method handler.
(Alias: @Tags())
src/http/users/route.ts
import { Controller, Get } from 'exisjs/decorators'import { ApiTags } from 'exisjs/swagger'
@ApiTags('Users', 'Authentication')@Controller()export default class UserController { @Get('/') findAll() { return [] }}@ApiOperation(options)
Attaches summary, description, operationId, and deprecated status to a route method.
(Alias: @Operation())
src/http/users/route.ts
import { Controller, Get, Param } from 'exisjs/decorators'import { ApiOperation } from 'exisjs/swagger'
@Controller()export default class UserController { @Get('/:id') @ApiOperation({ summary: 'Get user by UUID', description: 'Fetches user details from database', deprecated: false, }) getUser(@Param('id') id: string) { return { id, name: 'Alice' } }}@ApiResponse(options)
Defines an expected HTTP response status code and optional schema.
src/http/users/route.ts
import { Controller, Get, Param } from 'exisjs/decorators'import { ApiOperation, ApiResponse } from 'exisjs/swagger'import { tex } from 'exisjs/validator'
const UserSchema = tex.object({ id: tex.uuid(), name: tex.string(),})
@Controller()export default class UserController { @Get('/:id') @ApiResponse({ status: 200, description: 'User details found', schema: UserSchema, }) @ApiResponse({ status: 404, description: 'User not found' }) getUser(@Param('id') id: string) { return { id, name: 'Alice' } }}@ApiBearerAuth(name?: string)
Requires Bearer JWT authentication for this endpoint or controller.
(Alias: @BearerAuth())
src/http/users/route.ts
import { Controller, Get } from 'exisjs/decorators'import { ApiBearerAuth } from 'exisjs/swagger'
@ApiBearerAuth()@Controller()export default class UserController { @Get('/me') getMe() { return { id: 'user-123', role: 'admin' } }}@ApiSecurity(name: string, scopes?: string[])
Requires custom security scheme authentication for this endpoint or controller.
src/http/metrics/route.ts
import { Controller, Get } from 'exisjs/decorators'import { ApiSecurity } from 'exisjs/swagger'
@Controller()export default class MetricsController { @Get('/') @ApiSecurity('apiKeyAuth') getMetrics() { return { uptime: process.uptime() } }}@ApiExclude()
Excludes an endpoint or controller class from OpenAPI and Swagger generation.
src/http/internal/route.ts
import { Controller, Get } from 'exisjs/decorators'import { ApiExclude } from 'exisjs/swagger'
@Controller()export default class InternalController { @Get('/health') @ApiExclude() getHealth() { return { status: 'healthy' } }}@ApiProperty(options?: { description?: string; example?: any; required?: boolean })
Annotates a class property with metadata for OpenAPI schema models.
src/http/users/dto.ts
import { ApiProperty } from 'exisjs/swagger'
export class CreateUserDto { @ApiProperty({ description: 'Full name of the user', example: 'Alice Johnson', required: true }) name!: string
@ApiProperty({ description: 'Work email address', example: '[email protected]', required: true }) email!: string}Functions
swagger(config?: SwaggerConfig)
Convenience helper to mount Swagger/OpenAPI documentation on an ExisJS App instance (typically inside onStart or custom server setups).
src/http/server.ts
import { exis } from 'exisjs'import { swagger } from 'exisjs/swagger'
export default exis({ onStart(app) { swagger({ title: 'My API', path: '/docs' })(app) },})generateOpenApiSpec(routesOrApp, config)
Pure generator function that introspects routes, parameters, and TexEngine/Zod schemas and returns a complete OpenApiSpec object.
import { generateOpenApiSpec } from 'exisjs/swagger'
const spec = generateOpenApiSpec(app, { title: 'My API', version: '1.0.0' })renderDocumentationHtml(config)
Renders standalone HTML markup for Swagger UI or Scalar API reference.
import { renderDocumentationHtml } from 'exisjs/swagger'
const html = renderDocumentationHtml({ title: 'My API', specPath: '/docs/json', ui: 'scalar',})