# OpenAPI

> Nitro 可以根据你的路由处理器自动生成 OpenAPI 规范，并提供交互式 API 文档。

Nitro 会扫描所有路由处理器，提取通过 `defineRouteMeta` 定义的元数据，并生成一份 [OpenAPI 3.1.0](https://spec.openapis.org/oas/v3.1.0) 规范。内置的 [Scalar](https://scalar.com/) 和 [Swagger UI](https://swagger.io/tools/swagger-ui/) 界面让你可以直接在浏览器中浏览并测试 API。

<important>

OpenAPI 支持目前仍处于实验阶段。

</important>

## 启用 OpenAPI

在 Nitro 配置中启用 OpenAPI：

<code-group>

```ts [nitro.config.ts]
import { defineConfig } from "nitro";

export default defineConfig({
  experimental: {
    openAPI: true,
  },
});
```

</code-group>

启用后，开发环境中会提供以下端点：

<table>
<thead>
  <tr>
    <th>
      端点
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        /_openapi.json
      </code>
    </td>
    
    <td>
      OpenAPI 3.1.0 JSON 规范
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /_scalar
      </code>
    </td>
    
    <td>
      Scalar API 参考界面
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /_swagger
      </code>
    </td>
    
    <td>
      Swagger UI
    </td>
  </tr>
</tbody>
</table>

## 路由元数据

在路由处理器文件中使用 `defineRouteMeta` 宏，为每个路由提供 OpenAPI 元数据。`openAPI` 属性接收标准的 OpenAPI [Operation Object](https://spec.openapis.org/oas/v3.1.0#operation-object)。

```ts [routes/api/hello.ts]
import { defineRouteMeta, defineHandler } from "nitro";

defineRouteMeta({
  openAPI: {
    tags: ["greeting"],
    description: "返回问候消息",
    responses: {
      200: { description: "问候成功" },
    },
  },
});

export default defineHandler(() => {
  return { message: "你好，世界！" };
});
```

<note>

`defineRouteMeta` 是一个构建期宏。元数据会在构建过程中被静态提取，不会为处理器增加任何运行时开销。

</note>

### 参数

路由参数（如 `:id`、`[id]`）会自动转换为 OpenAPI 路径参数。你也可以在 `parameters` 数组中定义额外的查询参数或请求头参数：

```ts [routes/api/users/[id].get.ts]
import { defineRouteMeta, defineHandler } from "nitro";

defineRouteMeta({
  openAPI: {
    tags: ["users"],
    description: "根据 ID 获取用户",
    parameters: [
      {
        in: "query",
        name: "include",
        description: "要包含的关联资源列表，使用逗号分隔",
        schema: { type: "string" },
      },
    ],
    responses: {
      200: { description: "已找到用户" },
      404: { description: "未找到用户" },
    },
  },
});

export default defineHandler((event) => {
  const { id } = event.context.params;
  return { id, name: "小明" };
});
```

在这个示例中，`id` 路径参数会根据路由模式自动推断，因此只需要声明额外的 `include` 查询参数。

### 响应 Schema

使用标准的 OpenAPI `responses` 对象来定义响应的内容类型和 Schema：

```ts [routes/api/status.ts]
import { defineRouteMeta, defineHandler } from "nitro";

defineRouteMeta({
  openAPI: {
    description: "返回当前服务器状态",
    responses: {
      200: {
        description: "服务器状态",
        content: {
          "application/json": {
            schema: {
              type: "object",
              properties: {
                status: { type: "string", enum: ["healthy", "degraded"] },
                uptime: { type: "number" },
              },
            },
          },
        },
      },
    },
  },
});

export default defineHandler(() => {
  return { status: "healthy", uptime: process.uptime() };
});
```

### 全局组件

使用 `$global` 属性定义可复用的 Schema，它们会被提升到 OpenAPI 规范顶层的 `components` 区域。这样你就可以在多个路由之间通过 `$ref` 复用这些共享 Schema。

```ts [routes/api/users.get.ts]
import { defineRouteMeta, defineHandler } from "nitro";

defineRouteMeta({
  openAPI: {
    tags: ["users"],
    description: "列出所有用户",
    responses: {
      200: {
        description: "用户列表",
        content: {
          "application/json": {
            schema: {
              type: "array",
              items: { $ref: "#/components/schemas/User" },
            },
          },
        },
      },
    },
    $global: {
      components: {
        schemas: {
          User: {
            type: "object",
            properties: {
              id: { type: "string" },
              name: { type: "string" },
              email: { type: "string", format: "email" },
            },
          },
        },
      },
    },
  },
});

export default defineHandler(() => {
  return [{ id: "1", name: "小明", email: "xiaoming@example.com" }];
});
```

定义之后，`User` Schema 就可以在任意其他路由中通过 `{ $ref: "#/components/schemas/User" }` 引用，而无需重复声明。

### 自动标签

路由会根据路径前缀自动分配标签：

<table>
<thead>
  <tr>
    <th>
      路径前缀
    </th>
    
    <th>
      标签
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        /api/
      </code>
    </td>
    
    <td>
      API Routes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        /_
      </code>
    </td>
    
    <td>
      Internal
    </td>
  </tr>
  
  <tr>
    <td>
      其他
    </td>
    
    <td>
      App Routes
    </td>
  </tr>
</tbody>
</table>

你也可以在 `openAPI` 元数据中显式指定 `tags` 来覆盖自动标签。

## 配置

通过顶层 `openAPI` 选项配置 OpenAPI 的行为：

```ts [nitro.config.ts]
import { defineConfig } from "nitro";

export default defineConfig({
  experimental: {
    openAPI: true,
  },
  openAPI: {
    meta: {
      title: "My API",
      description: "我的超棒 API",
      version: "2.0.0",
    },
  },
});
```

### `meta`

设置 API 元数据，这些内容会出现在规范的 `info` 对象中：

<table>
<thead>
  <tr>
    <th>
      属性
    </th>
    
    <th>
      默认值
    </th>
    
    <th>
      说明
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        title
      </code>
    </td>
    
    <td>
      <code>
        "Nitro Server Routes"
      </code>
    </td>
    
    <td>
      API 标题
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      API 描述
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        version
      </code>
    </td>
    
    <td>
      <code>
        "1.0.0"
      </code>
    </td>
    
    <td>
      API 版本
    </td>
  </tr>
</tbody>
</table>

### `route`

- 默认值：`"/_openapi.json"`

覆盖 OpenAPI JSON 规范的服务路径：

```ts [nitro.config.ts]
export default defineConfig({
  openAPI: {
    route: "/_docs/openapi.json",
  },
});
```

### `ui`

配置或禁用内置的 API 文档界面：

```ts [nitro.config.ts]
export default defineConfig({
  openAPI: {
    ui: {
      scalar: {
        route: "/_docs/scalar",
        theme: "purple",
      },
      swagger: {
        route: "/_docs/swagger",
      },
    },
  },
});
```

将任一 UI 设置为 `false` 即可禁用：

```ts [nitro.config.ts]
export default defineConfig({
  openAPI: {
    ui: {
      swagger: false,
    },
  },
});
```

<read-more title="Scalar Configuration" to="https://github.com/scalar/scalar">



</read-more>

## 生产环境

默认情况下，OpenAPI 端点只在开发环境中可用。若要在生产环境中启用，请设置 `production` 选项：

```ts [nitro.config.ts]
export default defineConfig({
  openAPI: {
    production: "runtime",
  },
});
```

<table>
<thead>
  <tr>
    <th>
      值
    </th>
    
    <th>
      行为
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code className="language-ts shiki shiki-themes github-light github-dark github-dark" language="ts" style="">
        <span class="suiK_">
          false
        </span>
      </code>
    </td>
    
    <td>
      在生产环境中禁用（默认）
    </td>
  </tr>
  
  <tr>
    <td>
      <code className="language-ts shiki shiki-themes github-light github-dark github-dark" language="ts" style="">
        <span class="sfrk1">
          "runtime"
        </span>
      </code>
    </td>
    
    <td>
      在每次请求时运行时生成规范
    </td>
  </tr>
  
  <tr>
    <td>
      <code className="language-ts shiki shiki-themes github-light github-dark github-dark" language="ts" style="">
        <span class="sfrk1">
          "prerender"
        </span>
      </code>
    </td>
    
    <td>
      在构建时生成规范，并作为静态文件提供
    </td>
  </tr>
</tbody>
</table>

如果规范在不同部署之间不会变化，建议使用 `"prerender"` 以获得最佳性能；如果你需要动态服务器信息或中间件访问能力，则使用 `"runtime"`。

<warning>

如果你在生产环境中启用了 OpenAPI，请务必使用合适的鉴权或访问控制来保护这些端点。

</warning>