What's tApi?

MOVETO typeto

!! Work in Progress

tApi 是一个优雅的 API 类型描述规范，借助 TypeScript 强大的类型系统，让 API 定义更自然、更具表现力。完全兼容 OpenAPI 3.0 规范，无缝对接现有工具生态。

核心特性

• TypeScript 语法定义 API
  用 class 定义数据模型，用 type 定义 API 操作。利用 TypeScript 类型系统提供完整的类型检查和推导能力：

  • 更自然的语法：class 定义数据模型，type 定义 API 操作
  • 完整的类型支持：泛型、联合类型、交叉类型等
  • 强大的类型推导：编译时类型检查和错误提示

• 元数据注解支持 支持 JSDoc、装饰器和行内注释三种方式添加元数据。可选字段、默认值等特性让 API 定义更加灵活：

  • JSDoc 注释：支持完整的 OpenAPI Schema 属性
  • 装饰器：提供声明式的元数据定义
  • 行内注释：简单直观的描述信息

• 站在巨人的肩膀上
  完整支持 OpenAPI 3.0 规范，让您在享受更好的开发体验的同时，还能复用丰富的工具生态：

  • 复用丰富的 OAS 工具生态
  • 使用现有的代码生成器
  • 集成已有的文档工具
  • 对接各类测试平台

• 开发者友好 享受 IDE 的智能提示、类型检查和代码重构能力。纯文本的 .ts 文件让版本控制和团队协作更加自然。

快速预览

// 定义数据模型
class Pet {
  /** Pet's id */
  id: int64 = 0;
  name: string;
  status: "available" | "pending" | "sold";
}

// 定义 API 操作
type createPet = {
  method: "POST";
  url: "{{SERVER}}/pet";
  body: Pet;
  resp: Resp<Pet> | Reason<"Invalid input">;
};

了解更多

• 📖 完整文档
• 🚀 快速开始
• 📋 API 规范

功能规划

• importer
  提供从 Postman、Swagger 和 OpenAPI 格式转换到 tApi 的功能，方便与现有工具集成。

• codegen
  支持自定义代码生成插件，生成不同语言和客户端请求层代码。

• runner
  支持 Mock 数据和 Test 脚本的运行，帮助开发者快速验证 API 的功能与行为。

• devtools
  开发 VSCode 插件和 GUI 客户端，进一步优化 API 描述的编辑和可视化体验。

灵感来源

tApi 的灵感来源于 Bruno。与 Bruno 自定义 DSL 不同，tApi 直接使用 TypeScript 语法描述 API，同时补全了 Bruno 在 Response 类型定义上的不足，提供更完整的 API 设计能力。

---

润色 by ChatGPT