Elysia OpenAPI Plugin

The openapi() function accepts a configuration object to customize the generated documentation.

Core Configuration

• enabled: (default: true) Enable or disable the plugin.
• openapiVersion: (default: '3.1.2') The OpenAPI document version to emit. Supports 3.0.x and 3.1.x.
• path: (default: '/openapi') The endpoint to expose the OpenAPI documentation frontend.
• specPath: (default: '/${path}/json') The endpoint to expose the OpenAPI specification in JSON format.
• provider: (default: 'scalar') The documentation frontend provider. Options are scalar, swagger, or null to disable the frontend.

Exclude Routes

Use the exclude object to hide specific parts of your API from the documentation:

• exclude.methods: A list of HTTP methods to exclude.
• exclude.paths: A list of paths to exclude.
• exclude.staticFile: (default: true) Exclude static file routes.
• exclude.tags: A list of tags to exclude.

Documentation & References

• documentation: Object containing OpenAPI documentation information.
• references: Additional OpenAPI references for each endpoint.

Provider Specific Config

• scalar: Configuration for the Scalar provider (follows Scalar config).
• swagger: Configuration for the SwaggerUI provider (follows Swagger config).

To use the plugin, import openapi from @elysia/openapi and register it using .use(openapi()) on your Elysia instance. The plugin automatically generates documentation based on your route definitions, including schemas provided via Elysia's t (TypeBox) validation. By default, the documentation frontend is available at /openapi.

import { Elysia, t } from 'elysia'
import { openapi } from '@elysia/openapi'

const app = new Elysia()
	.use(openapi())
	.get('/', () => 'hi', {
		response: t.String({ description: 'sample description' })
	})
	.post(
		'/json/:id',
		({ body, params: { id }, query: { name } }) => ({
			...body,
			id,
			name
		}),
		{
			params: t.Object({
				id: t.String()
			}),
			query: t.Object({
				name: t.String()
			}),
			body: t.Object({
				username: t.String(),
				password: t.String()
			}),
			response: t.Object(
				{
					username: t.String(),
					password: t.String(),
					id: t.String(),
					name: t.String()
				},
				{ description: 'sample description' }
			)
		}
	)
	.listen(3000)

The openapi() function accepts a configuration object of type ElysiaOpenAPIConfig.

Configuration Options

Exclude documentation

Use the exclude object to hide specific parts of your API from the documentation:

• exclude.methods: Array of HTTP methods to exclude.
• exclude.paths: Array of path strings to exclude.
• exclude.staticFile: Exclude static file routes.
• exclude.tags: Array of tag names to exclude.

app.use(openapi({
    path: '/docs',
    provider: 'swagger-ui',
    documentation: {
        info: {
            title: 'My API',
            version: '1.0.0'
        }
    },
    exclude: {
        tags: ['internal']
    }
}))

You can choose between scalar (default) and swagger-ui using the provider option. Each provider has its own specific configuration block:

• Scalar: Use the scalar key to pass ApiReferenceConfiguration. You can also specify a version for the CDN bundle or a custom cdn path (e.g., a local file or a specific unpkg URL).
• Swagger UI: Use the swagger key to pass options to SwaggerUIBundle. Supported options include theme (string or light/dark object), version (default 4.18.2), autoDarkMode, and cdn for custom bundle paths. Note that functional options like requestInterceptor are not supported.

// Scalar configuration example
openapi({
  provider: 'scalar',
  scalar: {
    version: 'latest',
    cdn: 'https://unpkg.com/@scalar/api-reference@1.13.10/dist/browser/standalone.js'
  }
})

// Swagger UI configuration example
openapi({
  provider: 'swagger-ui',
  swagger: {
    theme: { light: 'css-string', dark: 'css-string' },
    autoDarkMode: true
  }
})

The SwaggerUIRender function generates a complete HTML string to serve a Swagger UI documentation page. It takes OpenAPI information and configuration options to customize the look and feel of the documentation.

Configuration Options

When calling SwaggerUIRender, you can provide the following configuration via the config object:

• version (string, default: 'latest'): The version of swagger-ui-dist to use from the Unpkg CDN.
• theme (string | { light: string, dark: string }):
  • If a string, it is used as the CSS stylesheet URL.
  • If an object with light and dark keys, it provides specific stylesheets for different color schemes.
• cdn (string, default: uses version to build a URL): The URL for the swagger-ui-bundle.js script.
• autoDarkMode (boolean, default: true): If true, injects CSS to automatically apply a dark mode filter to the Swagger UI based on the user's system preference.
• ...rest: Any other valid SwaggerUIOptions (passed directly to the SwaggerUIBundle constructor).

Note: Functions passed in the configuration object are automatically stripped out before being stringified for the browser-side script.

import { SwaggerUIRender } from './src/swagger/index'
import { OpenAPIV3 } from 'openapi-types'

const info: OpenAPIV3.InfoObject = {
    title: 'My API',
    version: '1.0.0',
    description: 'An example API'
}

const config = {
    version: '5.17.11',
    autoDarkMode: true,
    // other SwaggerUIOptions
}

const html = SwaggerUIRender(info, config)

The ScalarRender function generates a complete HTML string used to serve the Scalar API documentation UI. It takes the OpenAPI information object, a configuration object, and an optional embedded specification string.

This function is typically used internally by @elysia/openapi to provide a visual interface for your API documentation. It injects the provided configuration and any custom CSS into a standalone HTML document that loads the Scalar library via the specified CDN.

import { ScalarRender } from './src/scalar/index'
import type { OpenAPIV3 } from 'openapi-types'

// Example usage (internal/manual implementation)
const html = ScalarRender(
  { title: 'My API', description: 'An example API' } as OpenAPIV3.InfoObject,
  { 
    cdn: 'https://cdn.jsdelivr.net/npm/@scalar/api-reference', 
    customCss: '.my-class { color: red; }' 
  },
  '{"openapi": "3.0.0", ...}' // embedSpec
);