如何为Next.js Route Handlers生成OpenAPI规范？

完全可以实现类似FastAPI的自动/半自动生成OpenAPI规范的效果，下面是几种可行的方案：

• 手动编写规范
  如果你的API路由数量不多，可直接基于Route Handler的逻辑手动编写OpenAPI YAML/JSON文件。将每个路由的HTTP方法、路径、请求参数、响应结构对应到OpenAPI的paths字段中即可。这种方式适合小型项目，无需额外依赖，但路由增多后维护成本会上升。

• 使用社区工具库
  已有不少第三方库能帮你简化生成流程：

  • next-swagger-doc：支持从Route Handler的JSDoc注释中提取信息生成OpenAPI文档。只需在路由文件上添加符合规范的注释，再运行脚本就能生成swagger.json或yaml文件，还能集成Swagger UI展示文档。
    示例代码：

  // app/api/users/route.js
  /**
   * @swagger
   * /api/users:
   *   get:
   *     summary: 获取用户列表
   *     responses:
   *       200:
   *         description: 成功返回用户列表
   *         content:
   *           application/json:
   *             schema:
   *               type: array
   *               items:
   *                 type: object
   *                 properties:
   *                   id:
   *                     type: string
   *                   name:
   *                     type: string
   */
  export async function GET() {
    return Response.json([{ id: '1', name: 'John' }]);
  }
  

  • openapi-nextjs：适合TypeScript项目，可扫描Route Handler文件，通过分析代码中的类型定义自动生成OpenAPI规范，减少重复注释的工作量。

• 自定义生成脚本
  若需要高度定制化的逻辑，可自行编写Node.js脚本：

  1. 遍历app/api目录下的所有Route Handler文件；
  2. 解析文件中暴露的HTTP方法（GET、POST等）和对应路由路径；
  3. 提取请求/响应的TypeScript类型定义或注释中的结构信息；
  4. 按照OpenAPI规范结构组装成JSON/YAML文件。
     这种方式灵活性最高，但需要自行维护解析逻辑，适合有特殊需求的项目。

和FastAPI的类型注解自动生成不同，Next.js目前没有官方内置的OpenAPI生成功能，但通过上述方案，同样能实现自动/半自动生成规范、展示API文档的效果。

内容的提问来源于stack exchange，提问作者John