ElysiaJS 中文文档

Appearance

Our Sponsors
Open in Anthropic

title: OpenAPI - Elysia 教程 layout: false search: false authors: [] head: - - meta - property: 'og:title' content: OpenAPI - Elysia Tutorial

- - meta
  - name: 'description'
    content: Elysia 围绕 OpenAPI 构建，并且开箱即用地支持 OpenAPI 文档。

- - meta
  - property: 'og:description'
    content: Elysia 围绕 OpenAPI 构建，并且开箱即用地支持 OpenAPI 文档。

OpenAPI ​

Elysia 围绕 OpenAPI 构建，并且开箱即用地支持 OpenAPI 文档。

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

typescript
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)

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

详细信息 ​

我们可以通过 detail 字段提供文档 API，该字段遵循 OpenAPI 3.0 规范（具有自动补全功能）：

typescript
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)

引用模型 ​

我们还可以使用 引用模型 定义可重用的模式：

typescript
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)

当我们定义了引用模型时，它将显示在 OpenAPI 文档的 Components 部分。

类型生成 ​

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

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

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

Drizzle

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

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

typescript
import { Elysia } from 'elysia'

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

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

浏览器环境 ​

遗憾的是，此功能需要 fs 模块来读取你的源代码，并且在此网络练习场中不可用。因为 Elysia 直接在你的浏览器中运行（而不是独立的服务器）。

你可以使用 类型生成示例仓库 在本地尝试此功能：

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

任务 ​

让我们使用预览功能 GET '/hono' 来查看我们的 Hono 路由是否正常工作。

尝试修改代码并查看它的变化！

Show answer

  • index.ts