OpenAPI plugin

Plugin for elysia to auto-generate an API documentation page.

Install with:

bun add @elysia/openapi@next

Then use it:

import { Elysia } from 'elysia'
import { openapi } from '@elysia/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.

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 generated documentation by setting detail.hide to true

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

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

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 the config that is accepted by the plugin

enabled

Default: true Enable/Disable the plugin

documentation

OpenAPI documentation information

@see https://spec.openapis.org/oas/v3.1.2.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

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

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

path

Default: ‘/openapi’

The endpoint to expose the OpenAPI documentation frontend

provider

Default: ‘scalar’

OpenAPI documentation frontend provider between:

scalar: Scalar
swagger-ui: Swagger UI
null: disable frontend

references

Additional OpenAPI reference for each endpoint

scalar

Scalar configuration, refers to Scalar config

Self-hosted Scalar bundle

Self-host the Scalar bundle and disable CDN Fonts.

Note: cdn is an Elysia OpenAPI plugin option (not part of Scalar’s own config); it overrides the URI to the Scalar bundle.

    openapi({
      scalar: {
        cdn: "/public/scalar-standalone.min.js", // plugin override for Scalar bundle URI (self-hosted)
        withDefaultFonts: false, // disable Scalar’s default font CDN
      },
    })

specPath

Default: ${path}/json

The endpoint to expose the OpenAPI specification in JSON format

swagger

Swagger config, refers to Swagger config