ElysiaJS 中文网

主题

OpenAPI 插件 ​

¥OpenAPI Plugin

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

¥Plugin for elysia to auto-generate API documentation page.

使用以下工具安装：

¥Install with:

bash
bun add @elysiajs/openapi

然后使用它：

¥Then use it:

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

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

访问 /openapi 将显示一个 Scalar UI，其中包含 Elysia 服务器生成的端点文档。你还可以访问 /openapi/json 处的原始 OpenAPI 规范。

¥Accessing /openapi would show you a Scalar UI with the generated endpoint documentation from the Elysia server. You can also access the raw OpenAPI spec at /openapi/json.

提示

本页为插件配置参考。

¥This page is the plugin configuration reference.

如果你正在寻找常见模式或 OpenAPI 的高级用法，请查看 模式：OpenAPI。

¥If you're looking for a common patterns or an advanced usage of OpenAPI, check out Patterns: OpenAPI

详情 ​

¥Detail

detail 扩展了 OpenAPI 操作对象

¥detail extends the OpenAPI Operation Object

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

¥The detail field is an object that can be used to describe information about the route for API documentation.

它可能包含以下字段：

¥It may contain the following fields:

detail.hide ​

你可以通过将 detail.hide 设置为 true 来隐藏 Swagger 页面中的路由。

¥You can hide the route from the Swagger page by setting detail.hide to true

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。

¥Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is false.

detail.description ​

操作行为的详细说明。

¥A verbose explanation of the operation behavior.

detail.summary ​

操作的简要概述。

¥A short summary of what the operation does.

配置 ​

¥Config

以下是插件接受的配​​置。

¥Below is a config which is accepted by the plugin

enabled ​

@default true Enable/Disable the plugin

文档 ​

¥documentation

OpenAPI 文档信息

¥OpenAPI documentation information

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

exclude ​

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

¥Configuration to exclude paths or methods from documentation

exclude.methods ​

应从文档中排除的方法列表

¥List of methods to exclude from documentation

exclude.paths ​

应从文档中排除的路径列表

¥List of paths to exclude from documentation

exclude.staticFile ​

@default true

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

¥Exclude static file routes from documentation

exclude.tags ​

应从文档中排除的标签列表

¥List of tags to exclude from documentation

mapJsonSchema ​

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

¥A custom mapping function from Standard schema to OpenAPI schema

示例 ​

¥Example

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

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

path ​

@default '/openapi'

用于公开 OpenAPI 文档前端的端点

¥The endpoint to expose OpenAPI documentation frontend

provider ​

@default 'scalar'

OpenAPI 文档前端介于：

¥OpenAPI documentation frontend between:

references ​

为每个端点添加额外的 OpenAPI 参考

¥Additional OpenAPI reference for each endpoint

scalar ​

标量配置，请参阅 Scalar 配置

¥Scalar configuration, refers to Scalar config

specPath ​

@default '/${path}/json'

用于公开 JSON 格式 OpenAPI 规范的端点

¥The endpoint to expose OpenAPI specification in JSON format

swagger ​

Swagger 配置，引用 Swagger 配置

¥Swagger config, refers to Swagger config

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

¥Below you can find the common patterns to use the plugin.