ElysiaJS 中文文档

Appearance

我们的赞助商

OpenAPI 插件 ​

elysia 的插件，用于自动生成 API 文档页面。

使用以下命令安装：

bash
bun add @elysiajs/openapi

然后使用它：

typescript
import { 
Elysia
 } from 'elysia'
import { 
openapi
 } from '@elysiajs/openapi'

new 
Elysia
()
    .
use
(
openapi
())
    .
get
('/', () => 'hello')
    .
post
('/hello', () => 'OpenAPI')
    .
listen
(3000)

访问 /openapi 将显示带有从 Elysia 服务器生成的端点文档的 Scalar UI。您也可以在 /openapi/json 访问原始 OpenAPI 规范。

TIP

此页面是插件配置参考。

如果您正在寻找 OpenAPI 的常见模式或高级用法，请查看 Patterns: OpenAPI

详细信息 ​

detail 扩展了 OpenAPI Operation Object

detail 字段是一个对象，可用于描述路由的 API 文档信息。

它可以包含以下字段：

detail.hide ​

通过将 detail.hide 设置为 true，您可以从 Swagger 页面隐藏路由

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

new Elysia().use(openapi()).post('/sign-in', ({ body }) => body, {
    body: t.Object(
        {
            username: t.String(),
            password: t.String()
        },
        {
            description: 'Expected a username and password'
        }
    ),
    detail: {
        hide: true
    } 
})

detail.deprecated ​

声明此操作已弃用。消费者应避免使用声明的操作。默认值为 false。

detail.description ​

操作行为的详细解释。

detail.summary ​

操作功能的简短摘要。

配置 ​

以下是插件接受的配置

enabled ​

@default true 启用/禁用插件

documentation ​

OpenAPI 文档信息

@see https://spec.openapis.org/oas/v3.0.3.html

exclude ​

从文档中排除路径或方法的配置

exclude.methods ​

从文档中排除的方法列表

exclude.paths ​

从文档中排除的路径列表

exclude.staticFile ​

@default true

从文档中排除静态文件路由

exclude.tags ​

从文档中排除的标签列表

mapJsonSchema ​

从标准 schema 到 OpenAPI schema 的自定义映射函数

示例 ​

typescript
import { openapi } from '@elysiajs/openapi'
import { toJsonSchema } from '@valibot/to-json-schema'

openapi({
	mapJsonSchema: {
	  	valibot: toJsonSchema
  	}
})

path ​

@default '/openapi'

暴露 OpenAPI 文档前端的端点

provider ​

@default 'scalar'

OpenAPI 文档前端选项：

references ​

每个端点的附加 OpenAPI 引用

scalar ​

Scalar 配置，参考 Scalar config

specPath ​

@default '/${path}/json'

暴露 JSON 格式 OpenAPI 规范的端点

swagger ​

Swagger 配置，参考 Swagger config

以下是使用该插件的常见模式。