OpenAPI Plugin
A plugin for Elysia that auto‑generates an API documentation page.

Install with:

bun add @elysiajs/openapi  

import { Elysia } from 'elysia'
import { openapi } from '@elysiajs/openapi'

new Elysia()
  .use(openapi())
  .get('/', () => 'hello')
  .post('/hello', () => 'OpenAPI')
  .listen(3000)

Accessing <your-host>/openapi will show a Scalar UI with the generated endpoint documentation from the Elysia server.
The raw OpenAPI spec is available at <your-host>/openapi/json.

Tip – This page is the plugin configuration reference.
For common patterns or advanced usage, see Patterns: OpenAPI.

Detail

detail extends the OpenAPI Operation Object.
The detail field can contain the following:

detail.hide

Hide the route from the Swagger page.

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

new Elysia()
  .use(openapi())
  .post(
    '/sign-in',
    ({ body }) => body,
    {
      body: t.Object({
        username: t.String(),
        password: t.String()
      }, {
        description: 'Expected a username and password'
      }),
      detail: {
        hide: true
      }
    }
  )

detail.deprecated

Declare this operation to be deprecated. Consumers should refrain from using the operation.
Default: false.

detail.description

A verbose explanation of the operation behavior.

detail.summary

A short summary of what the operation does.

Config

The plugin accepts the following configuration object.

enabled

enabled: true   // defaults to true

Enable / disable the plugin.

documentation

OpenAPI documentation information – see the official OpenAPI specification.

exclude

Configuration to exclude paths or methods from documentation.

exclude.methods

List of methods to exclude.

exclude.paths

List of paths to exclude.

exclude.staticFile

exclude.staticFile: true   // defaults to true

Exclude static file routes from documentation.

exclude.tags

List of tags to exclude from documentation.

mapJsonSchema

A custom mapping function from a standard schema to an OpenAPI schema.

Example

import { openapi } from '@elysiajs/openapi'
import { toJsonSchema } from '@valibot/to-json-schema'

openapi({
  mapJsonSchema: {
    valibot: toJsonSchema
  }
})

path

path: '/openapi'   // defaults to '/openapi'

Endpoint to expose the OpenAPI documentation frontend.

provider

provider: 'scalar'   // defaults to 'scalar'

OpenAPI documentation frontend:

• scalar – Scalar
• swagger-ui – Swagger UI
• null – disable frontend

references

Additional OpenAPI references for each endpoint.

scalar

Scalar configuration – see the Scalar config.

specPath

specPath: '/openapi/json'   // defaults to '/${path}/json'

Endpoint to expose the OpenAPI specification in JSON format.

swagger

Swagger config – see the Swagger UI configuration docs.

Below you can find the common patterns to use the plugin.