Interactive Playground

在线编辑器已在低内存构建中禁用

当前部署环境只有 2C4G。为了避免构建阶段因 Monaco、Rollup Browser 和 类型分析导致 OOM，这个版本只保留教程内容，不内嵌在线 Playground。

bun run build:full

如需完整交互体验，请在更高配置环境执行上面的完整构建命令。

OpenAPI ​

Elysia 是基于 OpenAPI 构建的，开箱即支持 OpenAPI 文档。

我们可以使用 OpenAPI 插件 来展示 API 文档。

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

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

添加后，我们可以在 /openapi 访问我们的 API 文档。

详细信息 ​

我们可以通过 detail 字段提供符合 OpenAPI 3.0 规范的 API 文档（带自动补全）：

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

new Elysia()
	.use(openapi())
	.post(
		'/',
		({ body }) => body,
		{
			body: t.Object({
				age: t.Number()
			}),
			detail: { 
				summary: '创建用户', 
				description: '根据年龄创建用户', 
				tags: ['用户'], 
			} 
		}
	)
	.listen(3000)

参考模型 ​

我们也可以定义可重用的模式，使用 参考模型：

typescript
import { Elysia, t } from 'elysia'
import { openapi } from '@elysia/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: '创建用户',
				description: '根据年龄创建用户',
				tags: ['用户'],
			}
		}
	)
	.listen(3000)

当我们定义一个参考模型时，它将显示在 OpenAPI 文档的 组件 部分。

类型生成 ​

OpenAPI 类型生成 可以自动为您的 API 生成文档，无需手动注释，直接从 TypeScript 类型推断。无需 Zod、TypeBox、手动接口声明等。

此功能是 Elysia 独有的，其他 JavaScript 框架中不可用。

例如，如果您使用 Drizzle ORM 或 Prisma，Elysia 可以直接从查询中推断出模式。

Drizzle

从 Elysia 路由处理程序返回的 Drizzle 查询将被自动推断为 OpenAPI 模式。

要使用 OpenAPI 类型生成，只需在 openapi 插件之前使用 fromTypes 插件。

typescript
import { Elysia } from 'elysia'

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

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

浏览器环境 ​

遗憾的是，该功能需要 fs 模块来读取您的源代码，无法在此 Web Playground 使用。因为 Elysia 是直接在您的浏览器中运行（而非独立服务器）。

您可以在本地尝试此功能，使用 Type Gen 示例仓库：

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

作业 ​

让我们使用预览页面 GET '/openapi'，看看我们的 API 文档效果。

这个 API 文档是从你的代码自动生成的。

尝试修改代码，看看文档如何变化！