Quick Start
Plugins
Quick Start
Plugins

Swagger Plugin

This plugin generates a Swagger endpoint for an Elysia server

Install with:

bun add @elysiajs/swagger

Then use it:

import { Elysia } from "elysia";
import { swagger } from "@elysiajs/swagger";

new Elysia()
  .use(swagger())
  .get("/", () => "hi")
  .post("/hello", () => "world")
  .listen(8080);

Accessing /swagger would show you a Swagger endpoint with generated endpoint from Elysia server.

Config

Below is a config which is accepted by the plugin

swagger

Configuration for customizing Swagger.

Please refers 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 swagger endpoint by setting path in plugin config.

import { Elysia } from "elysia";
import { swagger } from "@elysiajs/swagger";

new Elysia()
  .use(
    swagger({
      path: "/v2/swagger",
    })
  )
  .listen(8080);

Customize Swagger info

import { Elysia } from "elysia";
import { swagger } from "@elysiajs/swagger";

new Elysia()
  .use(
    swagger({
      documentation: {
        info: {
          title: "Elysia Documentation",
          version: "1.0.0",
        },
      },
    })
  )
  .listen(8080);

Using Tags

Elysia has the ability to separate the endpoints into groups by using Swaggers tag system

Firstly define the available tags in the swagger config object

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

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