Skip to content

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 /swagger/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

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.