OpenAPI

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

Nitro 会扫描所有路由处理器，提取通过 defineRouteMeta 定义的元数据，并生成一份 OpenAPI 3.1.0 规范。内置的 Scalar 和 Swagger UI 界面让你可以直接在浏览器中浏览并测试 API。

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

启用 OpenAPI

在 Nitro 配置中启用 OpenAPI：

import { defineConfig } from "nitro";

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

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

端点	说明
`/_openapi.json`	OpenAPI 3.1.0 JSON 规范
`/_scalar`	Scalar API 参考界面
`/_swagger`	Swagger UI

路由元数据

在路由处理器文件中使用 defineRouteMeta 宏，为每个路由提供 OpenAPI 元数据。openAPI 属性接收标准的 OpenAPI Operation Object。

routes/api/hello.ts

import { defineRouteMeta, defineHandler } from "nitro";

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

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

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

参数

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

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：

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。

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" } 引用，而无需重复声明。

自动标签

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

路径前缀	标签
`/api/`	API Routes
`/_`	Internal
其他	App Routes

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

配置

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

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 对象中：

属性	默认值	说明
`title`	`"Nitro Server Routes"`	API 标题
`description`	—	API 描述
`version`	`"1.0.0"`	API 版本

`route`

默认值："/_openapi.json"

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

nitro.config.ts

export default defineConfig({
  openAPI: {
    route: "/_docs/openapi.json",
  },
});

`ui`

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

nitro.config.ts

export default defineConfig({
  openAPI: {
    ui: {
      scalar: {
        route: "/_docs/scalar",
        theme: "purple",
      },
      swagger: {
        route: "/_docs/swagger",
      },
    },
  },
});

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

nitro.config.ts

export default defineConfig({
  openAPI: {
    ui: {
      swagger: false,
    },
  },
});

生产环境

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

nitro.config.ts

export default defineConfig({
  openAPI: {
    production: "runtime",
  },
});

值	行为
`false`	在生产环境中禁用（默认）
`"runtime"`	在每次请求时运行时生成规范
`"prerender"`	在构建时生成规范，并作为静态文件提供

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

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

生命周期

了解 Nitro 如何运行并为你的应用提供传入请求服务。

插件

使用插件来扩展 Nitro 的运行时行为。