一个现代化的 TypeScript 优先的 OpenAPI 文档生成器，通过分析代码和 JSDoc 注释自动生成全面、准确的 API 文档。
- 📝 JSDoc 驱动 - 使用熟悉的 JSDoc 语法描述 API，自动转换为 OpenAPI 3.1 文档
- 🤖 智能分析 - 基于代码静态分析，自动推断 HTTP 方法、路径、参数等信息
- 🎯 零侵入式 - 无需修改现有代码结构或添加装饰器，与现有项目完美融合
- 🛡️ Zod 支持 - 原生支持 Zod Schema，享受类型安全的同时自动生成 JSON Schema
- 🔌 多框架 - 支持 Express、Fastify、Koa 等主流 Node.js 框架
- ⚙️ 可扩展 - 插件化架构支持自定义标签解析器和配置选项
npm install api-morph
# 或者
pnpm add api-morph
# 或者
yarn add api-morph// schema.ts
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"],
}),
});// index.ts
import {
generateDocument,
generateSwaggerUI,
getSwaggerUIAssetInfo,
zodValidator,
} from "api-morph";
import express from "express";
import { UpdateUserDto, UpdateUserVo, UserIdDto } from "./schema";
const app = express();
app.use(express.json());
// 提供 Swagger UI 静态资源
app.use(express.static(getSwaggerUIAssetInfo().assetPath));
/**
* @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 的文档示例",
},
});
// 提供 OpenAPI JSON 和 Swagger UI
app.get("/openapi.json", (req, res) => res.json(openapi));
app.get("/swagger-ui", (req, res) => {
res.send(generateSwaggerUI({ url: "/openapi.json" }));
});
app.listen(3000, () => {
console.log("访问 http://localhost:3000/swagger-ui 查看 API 文档");
});完整的文档和 API 参考请访问我们的官方文档站点。
- ✅ Express
- ✅ Fastify（即将支持）
- ✅ Koa（即将支持）
- ✅ NestJS（即将支持）
本项目基于 MIT 许可证开源。