elysiajs-openapi

elysiajs-openapi

Use this plugin to effortlessly expose a beautiful OpenAPI reference page from your ElysiaJS application with zero configuration. Just add the plugin to your Elysia app and you're good to go!

👉 Why use this over @elysiajs/swagger? This is a fork of @elysiajs/swagger with updated dependencies and a few opinionated changes. If @elysiajs/swagger suits your needs (and you don't need the latest version of Scalar API Reference), then by all means, use that instead.

Add it to your Elysia app

bun add elysiajs-openapi

Try it out

import { Elysia, t } from 'elysia'
import { openapi } from 'elysiajs-openapi'

const app = new Elysia()
    .use(openapi())
    .get('/', () => 'hi', { response: t.String({ description: 'sample description' }) })
    .post(
        '/json/:id',
        ({ body, params: { id }, query: { name } }) => ({
            ...body,
            id,
            name
        }),
        {
            params: t.Object({
                id: t.String()
            }),
            query: t.Object({
                name: t.String()
            }),
            body: t.Object({
                username: t.String(),
                password: t.String()
            }),
            response: t.Object({
                username: t.String(),
                password: t.String(),
                id: t.String(),
                name: t.String()
            }, { description: 'sample description' })
        }
    )
    .listen(8080);

Visit http://localhost:8080/docs to see the generated OpenAPI reference page ✨

Changes from @elysiajs/swagger

• Update core dependencies to the latest versions (at the time of writing)
  • Updates include Scalar API Reference, enabling useful features like persistAuth
  • Fix code to fully support these updates, passing all official tests
• Ability to set any theme for Scalar API Reference, not just elysiajs
• Rename plugin to openapi (was swagger)
• Change the default API Reference path to /docs (was /swagger)
• Change the default openapi.json path to /docs/json (was /swagger/json)

Give us a ⭐️

Hey! If you like this plugin, please give us a ⭐️ on GitHub so more people can find it. Thank you!

Configuration for nerds

provider

@default 'scalar'

Choose between Scalar API Reference & Swagger UI

scalar

Customize scalarConfig, refers to Scalar config

swagger

Customize Swagger config, refers to Swagger 3.0.3 config

path

@default '/docs'

The endpoint to expose Swagger UI

excludeStaticFile

@default true

Determine if Swagger should exclude static files.

exclude

@default []

Paths to exclude from the Swagger endpoint