Introducing OpenAPI Type Gen for Elysia

API documentation plays a crucial role in the development of an API.

Contacting teams, vendors, or third-party services often requires a well-documented API to ensure smooth integration and collaboration.

Most frameworks today leave the burden of manual OpenAPI annotation on developers. This can be time-consuming, error-prone, and difficult to maintain as the API evolves.

We believe that API documentation should be effortless and automatic, allowing developers to focus on building great APIs without worrying about the documentation.

That’s why we built around OpenAPI from the ground up with Elysia.

• We make sure that schema can be used for data validation, type inference, and OpenAPI annotation all from a single source of truth.
• We provide an integration with Standard Schema (Zod, Valibot, etc.), and turn it into OpenAPI documentation when possible.
• We have a 1-liner OpenAPI plugin that adds a beautiful UI to interact with your API with Scalar.

Elysia running with Scalar UI from Elysia OpenAPI plugin from 1 line

But even with an already exceptional experience, we want to push it even further.

Today, we are excited to announce the release of OpenAPI Type Gen to generate OpenAPI documentation from your Elysia code without any manual annotation.

We dream of a world where you just write your code, and the documentation is created automatically, and accurately without any manual annotation at all.

The closest thing we have is with Python’s FastAPI that can generate OpenAPI documentation from pydantic models. But it is limited to only pydantic models, and cannot be used with other libraries or types.

Elysia Type Gen brings a similar experience to TypeScript, without that limitation, allowing you to turn any TypeScript type into OpenAPI documentation automatically from any library not limited to Elysia.

Elysia references the body type in a response schema automatically, listing all the possible response status codes without any manual schema annotation at all.

It takes 1 line of code to generate OpenAPI documentation from your Elysia code directly from TypeScript type without any annotation at all.

For the first time ever, you can now document your API automatically without any manual annotation for real. It just works, out of the box with any library.

It works with an existing Elysia codebase and schema definitions without any breaking changes or additional configuration like type transformer at all (eg. Typia).

Type Gen co-exists with existing schema definitions by prioritizing the existing schema definition first before falling back to inferring from types.

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

It’s also compatible with any TypeScript library even complex types from modern libraries like Drizzle, and Prisma out of the box.

OpenAPI Type Gen also supports complex scenarios like multiple statuses from lifecycle/macro that overlap with each other, separated by multiple response status codes.

Each status code can return multiple values, which will be handled by Elysia as a union type for every possible response under the same status code, listing all the possible return values accurately.

Listing multiple response status codes from a union type automatically.

This is something profound, and can hardly be replicated by any other framework.

To add OpenAPI Type Gen to your codebase, simply:

1. export an Elysia instance
2. provide root Elysia file path (if not provided, Elysia will use src/index.ts)

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

export const app = new Elysia()
  .use(
    openapi({
      references: fromTypes()
    })
  )

Elysia Type Gen will analyze your Elysia instance and generate the OpenAPI documentation automatically on the fly, no build step required.

The documentation for OpenAPI Type Gen can be found at Patterns: OpenAPI.

While most web frameworks require a lot of effort and manual annotation to create API documentation, Elysia can write API documentation for you, and there are no other frameworks that come close to this experience.

This is only possible thanks to Elysia’s spectacular support for end-to-end type safety.

We are excited to see how it will help you to create and maintain high-quality API documentation with minimal effort with Elysia.

You can try it out today by updating @elysia/openapi to the latest version or experimenting with our example setup from GitHub repository.