Typia项目新增对JSDoc @example标签的支持

背景介绍

Typia是一个强大的TypeScript工具库，主要用于类型验证和JSON模式生成。在最新版本中，Typia增加了对JSDoc中@example标签的支持，这一功能对于开发者自动生成API文档特别有价值。

功能实现

Typia 6.10.3版本引入了两种新的类型标记方式：

1. tags.Example<T> - 用于为单个属性指定示例值
2. tags.Examples<T> - 用于为属性指定多个示例值

这些类型标记可以直接在接口定义中使用，为生成的JSON Schema提供示例数据。例如：

import { tags } from "typia";

interface User {
    id: string & tags.Format<"uuid">;
    name: string & tags.MinLength<3> & tags.MaxLength<20>;
    age: number & tags.Minimum<18> & tags.Maximum<100>;
    email: string & tags.Format<"email">;
    // 使用tags.Example提供示例值
    status: "active" | "inactive" | "pending" & tags.Example<"active">;
}

技术优势

1. 类型安全：示例值与类型定义保持严格一致，避免文档与实际接口不匹配的问题
2. 代码整洁：相比在JSDoc中写示例，类型标记方式更符合TypeScript的编程风格
3. 文档自动化：生成的JSON Schema可直接用于Swagger等API文档工具
4. 多示例支持：通过tags.Examples可以为一个属性提供多个示例值

使用场景

这一功能特别适合以下场景：

1. API文档生成：自动为Swagger/OpenAPI文档提供示例数据
2. 前端开发：为mock数据提供标准示例
3. 测试用例：基于示例值生成测试数据
4. 表单开发：为表单字段提供默认值参考

注意事项

目前该功能存在以下限制：

1. 尚不支持为对象类型的属性添加示例
2. 与JSDoc中的@example标签相比，类型标记方式需要修改实际代码
3. 在Prisma等ORM工具中可能无法使用类型标记语法

未来展望

Typia团队表示未来可能会考虑支持JSDoc中的@example标签，以满足那些不希望修改实际代码结构的需求。这将为开发者提供更多灵活性，可以根据项目需求选择最适合的方式添加示例数据。

这一功能的加入使得Typia在API开发领域的实用性进一步提升，特别是在文档自动化方面迈出了重要一步。