feat: support koa

Author: yingzhi0808

README.md

@@ -79,7 +79,7 @@ import {
   generateDocument,
   generateSwaggerUI,
   getSwaggerUIAssetInfo,
-  validateRequest,
+  zodValidator,
 } from "api-morph";
 import express from "express";
 import { UpdateUserDto, UpdateUserVo, UserIdDto } from "./schema";
@@ -98,7 +98,7 @@ app.use(express.static(getSwaggerUIAssetInfo().assetPath));
  */
 app.put(
   "/api/users/:id",
-  validateRequest({ params: UserIdDto, body: UpdateUserDto }),
+  zodValidator({ params: UserIdDto, body: UpdateUserDto }),
   (req, res) => {
     const { id } = req.params;
     const { email, username } = req.body;

ROADMAP.md

@@ -1,11 +1,7 @@
-- [ ] 设计一个API支持用户覆盖最终生成的文档
 - [ ] 支持配置路径全局前缀，需要适配框架的写法，或者自己封装
 - [ ] 模仿 nestjs 添加 addxxxAuth 方法
 - [ ] 模仿 nestjs 添加 addGlobalResponse/addGlobalParameter 方法
 - [ ] 更严格的校验（对 JSON Schema 进行校验）
-- [ ] 支持将handler写成独立的函数
-- [ ] 支持在注释中通过 @link 引用 TypeScript 类型并生成 schema
 - [ ] 支持使用 new Router() 定义路由，并对tag分组，需要新设计 API
 - [ ] 支持通过 ClassValidator 校验请求参数并生成 schema
 - [ ] 适配其他 Node.js 框架
-- [ ] 支持编译时和运行时两种模式

examples/express/index.ts

@@ -0,0 +1,62 @@
+import { generateDocument } from "api-morph";
+import { setupSwaggerUI, zodValidator } from "api-morph/express";
+import express from "express";
+import { UpdateUserDto, UpdateUserVo, UserIdDto } from "./schema";
+
+const app = express();
+
+app.use(express.json());
+
+/**
+ * @summary 更新用户信息
+ * @description 更新指定用户的个人信息
+ * @tags users
+ * @response 200 {@link UpdateUserVo} 更新用户信息成功
+ */
+app.put(
+  "/api/users/:id",
+  zodValidator({
+    params: UserIdDto,
+    body: UpdateUserDto,
+  }),
+  (req, res) => {
+    const { id } = req.params;
+    const { email, username } = req.body;
+
+    res.json({
+      id,
+      email,
+      username,
+    });
+  },
+);
+
+// 生成 OpenAPI 文档
+const openapi = await generateDocument(
+  {
+    info: {
+      version: "1.0.0",
+      title: "用户管理 API",
+      description: "这是一个用户管理 API 的文档示例",
+    },
+  },
+  {
+    parserOptions: {
+      include: ["examples/express/**/*.ts"],
+    },
+  },
+);
+
+// 提供 OpenAPI JSON 文档
+app.get("/openapi.json", (_req, res) => {
+  res.json(openapi);
+});
+
+// 提供 Swagger UI 界面
+setupSwaggerUI("/swagger-ui", app);
+
+const port = 3000;
+app.listen(port, () => {
+  console.log(`Example app listening on port ${port}`);
+  console.log(`访问 http://localhost:${port}/swagger-ui 查看 API 文档`);
+});

examples/express/schema.ts

@@ -0,0 +1,36 @@
+import { z } from "zod/v4";
+
+export const UserIdDto = z.object({
+  id: z.string().meta({ description: "用户ID" }),
+});
+
+export const UpdateUserDto = z.object({
+  email: z.email().meta({
+    description: "用户邮箱地址",
+    examples: ["[email protected]"],
+  }),
+  username: z
+    .string()
+    .min(3)
+    .max(50)
+    .meta({
+      description: "用户名",
+      examples: ["John Doe"],
+    }),
+});
+
+export const UpdateUserVo = z.object({
+  id: z.string().meta({ description: "用户ID" }),
+  email: z.email().meta({
+    description: "用户邮箱地址",
+    examples: ["[email protected]"],
+  }),
+  username: z
+    .string()
+    .min(3)
+    .max(50)
+    .meta({
+      description: "用户名",
+      examples: ["John Doe"],
+    }),
+});

examples/koa/index.ts

@@ -0,0 +1,64 @@
+import Router from "@koa/router";
+import { generateDocument } from "api-morph";
+import { setupSwaggerUI, zodValidator } from "api-morph/koa";
+import Koa from "koa";
+import { UpdateUserDto, UpdateUserVo, UserIdDto } from "./schema";
+
+const app = new Koa();
+const router = new Router();
+
+/**
+ * @summary 更新用户信息
+ * @description 更新指定用户的个人信息
+ * @tags users
+ * @response 200 {@link UpdateUserVo} 更新用户信息成功
+ */
+router.put(
+  "/api/users/:id",
+  zodValidator({
+    params: UserIdDto,
+    body: UpdateUserDto,
+  }),
+  (ctx) => {
+    const { id } = ctx.params;
+    const { email, username } = ctx.request.body;
+
+    ctx.body = {
+      id,
+      email,
+      username,
+    };
+  },
+);
+
+app.use(router.routes()).use(router.allowedMethods());
+
+// 生成 OpenAPI 文档
+const openapi = await generateDocument(
+  {
+    info: {
+      version: "1.0.0",
+      title: "用户管理 API",
+      description: "这是一个用户管理 API 的文档示例",
+    },
+  },
+  {
+    parserOptions: {
+      include: ["examples/koa/**/*.ts"],
+    },
+  },
+);
+
+// 提供 OpenAPI JSON 文档
+router.get("/openapi.json", (ctx) => {
+  ctx.body = openapi;
+});
+
+// 提供 Swagger UI 界面
+setupSwaggerUI("/swagger-ui", app);
+
+const port = 3000;
+app.listen(port, () => {
+  console.log(`Example app listening on port ${port}`);
+  console.log(`访问 http://localhost:${port}/swagger-ui 查看 API 文档`);
+});

examples/koa/schema.ts

@@ -0,0 +1,36 @@
+import { z } from "zod/v4";
+
+export const UserIdDto = z.object({
+  id: z.string().meta({ description: "用户ID" }),
+});
+
+export const UpdateUserDto = z.object({
+  email: z.email().meta({
+    description: "用户邮箱地址",
+    examples: ["[email protected]"],
+  }),
+  username: z
+    .string()
+    .min(3)
+    .max(50)
+    .meta({
+      description: "用户名",
+      examples: ["John Doe"],
+    }),
+});
+
+export const UpdateUserVo = z.object({
+  id: z.string().meta({ description: "用户ID" }),
+  email: z.email().meta({
+    description: "用户邮箱地址",
+    examples: ["[email protected]"],
+  }),
+  username: z
+    .string()
+    .min(3)
+    .max(50)
+    .meta({
+      description: "用户名",
+      examples: ["John Doe"],
+    }),
+});

package.json

@@ -21,6 +21,8 @@
     "swagger-generator",
     "express-openapi",
     "express-swagger",
+    "koa-openapi",
+    "koa-swagger",
     "zod-openapi",
     "zod-swagger"
   ],
@@ -34,6 +36,11 @@
       "types": "./dist/express.d.ts",
       "import": "./dist/express.js",
       "require": "./dist/express.js"
+    },
+    "./koa": {
+      "types": "./dist/koa.d.ts",
+      "import": "./dist/koa.js",
+      "require": "./dist/koa.js"
     }
   },
   "main": "./dist/index.js",
@@ -67,9 +74,12 @@
   },
   "dependencies": {
     "@hyperjump/json-schema": "^1.16.0",
+    "@types/koa-static": "^4.0.4",
     "deepmerge": "^4.3.1",
+    "koa-static": "^5.0.0",
     "mime-types": "^3.0.1",
     "radashi": "^12.6.0",
+    "supertest": "^7.1.1",
     "swagger-ui-dist": "^5.25.3",
     "ts-morph": "^26.0.0",
     "typescript": "^5.8.3",
@@ -81,6 +91,7 @@
     "@oxc-node/core": "^0.0.29",
     "@types/mime-types": "^3.0.1",
     "@types/node": "^24.0.4",
+    "@types/supertest": "^6.0.3",
     "@vitest/coverage-v8": "^3.2.4",
     "lefthook": "^1.11.14",
     "nanoid": "^5.1.5",
@@ -95,7 +106,11 @@
     "vue": "^3.5.17"
   },
   "peerDependencies": {
+    "@koa/router": "^13.0.0",
     "@types/express": "^5.0.0",
-    "express": "^5.0.0"
+    "@types/koa": "^2.0.0",
+    "@types/koa__router": "^12.0.0",
+    "express": "^5.0.0",
+    "koa": "^3.0.0"
   }
 }