OpenAPI ​

Elysia is built around OpenAPI, and support OpenAPI documentation out of the box.

We can use OpenAPI plugin to show an API documentation.

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

new Elysia()
	.use(openapi()) 
	.post(
		'/',
		({ body }) => body,
		{
			body: t.Object({
				age: t.Number()
			})
		}
	)
	.listen(3000)

Once added, we can access our API documentation at /openapi.

Detail ​

We can provide document API by with a detail field which follows OpenAPI 3.0 specification (with auto-completion):

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

new Elysia()
	.use(openapi())
	.post(
		'/',
		({ body }) => body,
		{
			body: t.Object({
				age: t.Number()
			}),
			detail: { 
				summary: 'Create a user', 
				description: 'Create a user with age', 
				tags: ['User'], 
			} 
		}
	)
	.listen(3000)

Reference Model ​

We can also define reusable schema with Reference Model:

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

new Elysia()
	.use(openapi())
	.model({
		age: t.Object({ 
			age: t.Number() 
		}) 
	})
	.post(
		'/',
		({ body }) => body,
		{
			age: t.Object({ 
				age: t.Number() 
			}), 
			body: 'age',  
			detail: {
				summary: 'Create a user',
				description: 'Create a user with age',
				tags: ['User'],
			}
		}
	)
	.listen(3000)

When we defined a reference model, it will be shown in the Components section of the OpenAPI documentation.

Type Gen ​

This features is unique to Elysia, and is not available in other JavaScript frameworks.

For example, if you use Drizzle ORM or Prisma, Elysia can infer the schema directly from the query directly.

Returning Drizzle query from Elysia route handler will be automatically inferred into OpenAPI schema.

To use OpenAPI Type Gen, simply add apply fromTypes plugin before openapi plugin.

import { Elysia } from 'elysia'

import { openapi, fromTypes } from '@elysiajs/openapi'

new Elysia()
	.use(openapi({
		references: fromTypes() 
	}))
	.get('/', { hello: 'world' })
	.listen(3000)

Browser Environment ​

Unfortunately, this feature require a fs module to read your source code, and is not available this web playground. As Elysia is running directly in your browser (not a separated server).

You can try this feature locally with Type Gen Example repository:

git clone https://github.com/SaltyAom/elysia-typegen-example && \
cd elysia-typegen-example && \
bun install && \
bun run dev

Assignment ​

Let's use the preview to GET '/hono' to see if our Hono route is working.

Try to modify the code and see how it changes!