ElysiaJS

Appearance

Our Sponsors
Open in Anthropic

OpenAPI Plugin ​

Plugin for elysia to auto-generate API documentation page.

Install with:

bash
bun add @elysiajs/openapi

Then use it:

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

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

Accessing /openapi would show you a Scalar UI with the generated endpoint documentation from the Elysia server. You can also access the raw OpenAPI spec at /openapi/json.

TIP

This page is the plugin configuration reference.

If you're looking for a common patterns or an advanced usage of OpenAPI, check out Patterns: OpenAPI

Detail ​

detail extends the OpenAPI Operation Object

The detail field is an object that can be used to describe information about the route for API documentation.

It may contain the following fields:

detail.hide ​

You can hide the route from the Swagger page by setting detail.hide to true

typescript
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 ​

Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is false.

detail.description ​

A verbose explanation of the operation behavior.

detail.summary ​

A short summary of what the operation does.

Config ​

Below is a config which is accepted by the plugin

enabled ​

@default true Enable/Disable the plugin

documentation ​

OpenAPI documentation information

@see https://spec.openapis.org/oas/v3.0.3.html

exclude ​

Configuration to exclude paths or methods from documentation

exclude.methods ​

List of methods to exclude from documentation

exclude.paths ​

List of paths to exclude from documentation

exclude.staticFile ​

@default true

Exclude static file routes from documentation

exclude.tags ​

List of tags to exclude from documentation

mapJsonSchema ​

A custom mapping function from Standard schema to OpenAPI schema

Example ​

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

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

path ​

@default '/openapi'

The endpoint to expose OpenAPI documentation frontend

provider ​

@default 'scalar'

OpenAPI documentation frontend between:

references ​

Additional OpenAPI reference for each endpoint

scalar ​

Scalar configuration, refers to Scalar config

specPath ​

@default '/${path}/json'

The endpoint to expose OpenAPI specification in JSON format

swagger ​

Swagger config, refers to Swagger config

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