Skip to content

Swagger Plugin

This plugin generates a Swagger endpoint for an Elysia server

Install with:

bash
bun add @elysiajs/swagger

Then use it:

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

new Elysia()
    .use(swagger())
    .get('/', () => 'hi')
    .post('/hello', () => 'world')
    .listen(3000)

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

Config

Below is a config which is accepted by the plugin

provider

@default scalar

UI Provider for documentation. Default to Scalar.

scalar

Configuration for customizing Scalar.

Please refer to the Scalar config

swagger

Configuration for customizing Swagger.

Please refer to the Swagger specification.

excludeStaticFile

@default true

Determine if Swagger should exclude static files.

path

@default /swagger

Endpoint to expose Swagger

exclude

Paths to exclude from Swagger documentation.

Value can be one of the following:

  • string
  • RegExp
  • Array<string | RegExp>

Pattern

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

Change Swagger Endpoint

You can change the swagger endpoint by setting path in the plugin config.

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

new Elysia()
    .use(swagger({
        path: '/v2/swagger'
    }))
    .listen(3000)

Customize Swagger info

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

new Elysia()
    .use(swagger({
        documentation: {
            info: {
                title: 'Elysia Documentation',
                version: '1.0.0'
            }
        }
    }))
    .listen(3000)

Using Tags

Elysia can separate the endpoints into groups by using the Swaggers tag system

Firstly define the available tags in the swagger config object

typescript
app.use(
  swagger({
    documentation: {
      tags: [
        { name: 'App', description: 'General endpoints' },
        { name: 'Auth', description: 'Authentication endpoints' }
      ]
    }
  })
)

Then use the details property of the endpoint configuration section to assign that endpoint to the group

typescript
app.get('/', () => 'Hello Elysia', {
  detail: {
    tags: ['App']
  }
})

app.group('/auth', (app) =>
  app.post(
    '/sign-up',
    async ({ body }) =>
      db.user.create({
        data: body,
        select: {
          id: true,
          username: true
        }
      }),
    {
      detail: {
        tags: ['Auth']
      }
    }
  )
)

Which will produce a swagger page like the following image