介绍
api-morph 是一个现代化的 TypeScript 优先的 OpenAPI 文档生成器。它通过分析你的 TypeScript 代码和 JSDoc 注释,自动生成全面、准确的 API 文档。
为什么选择 api-morph?
核心理念
api-morph 的设计理念是 "代码即文档"。它能够:
- 自动分析代码结构 - 通过代码分析自动推断 HTTP 方法、路径、参数等信息
- 最小化手动配置 - 大部分 API 信息都能自动推断,只需要少量 JSDoc 注释
- 渐进式增强 - 可以根据需要逐步添加更详细的文档信息
🎯 解决核心痛点
在现代 API 开发中,保持文档与代码同步一直是个挑战:
- 文档滞后:手动维护文档容易遗漏更新
- 类型不一致:文档中的类型定义与实际代码不匹配
- 维护成本高:需要在多个地方维护相同的信息
- 框架束缚:许多工具要求特殊的代码结构或装饰器
api-morph 通过 零侵入式集成 和 智能分析 的理念解决这些问题,让你的 JSDoc 注释成为 API 文档的权威来源。
🚀 核心优势
📝 JSDoc 驱动的智能文档生成
- 直接在代码中使用熟悉的 JSDoc 注释语法
- 支持
@operation
、@response
、@parameter
等丰富标签 - 自动转换为标准的 OpenAPI 3.1 文档格式
🤖 代码结构智能分析
- 基于代码静态分析,自动识别函数签名和类型信息
- 智能推断 HTTP 方法、路径结构和参数关系
- 减少手动配置,提高文档生成效率
🎯 零侵入式集成
- 无需修改现有代码架构或添加特殊装饰器
- 兼容任何 TypeScript 项目结构和编码风格
- 保持代码的简洁性和可维护性
🛡️Zod Schema 原生支持
- 深度整合 Zod 类型验证库
- 直接使用 Zod schema 定义 API 数据结构
- 自动生成准确的 JSON Schema 文档
🔌 多框架无缝适配
- 支持 Express、Fastify、Koa、NestJS 等主流框架
- 提供统一的集成接口和配置方式
- 轻松在不同项目间复用文档方案
⚙️ 灵活的定制化能力
- 插件化架构支持自定义标签解析器
- 丰富的配置选项满足个性化需求
- 可扩展的解析器系统适应特殊场景
下一步
准备好开始了吗?查看我们的 快速开始指南 来创建你的第一个 API 文档。