如何让Typedoc中Zod推断类型的文档更美观？

下面是几个既能保留Zod运行时验证能力，又能生成简洁Typedoc文档的方案，无需维护两套类型：

1. 用@typedef注释优化类型别名显示 #

直接使用z.infer生成的类型别名会被Typedoc原样展示为z.infer<typeof schemaName>，给类型别名添加@typedef注释可以让Typedoc优先显示自定义描述，并展开实际类型：

import { z } from 'zod';

// 定义带描述的Zod Schema
const userSchema = z.object({
  name: z.string().optional().describe('用户名称'),
  age: z.number().describe('用户年龄')
});

/**
 * 用户信息类型
 * @typedef {z.infer<typeof userSchema>} User
 */
export type User = z.infer<typeof userSchema>;

// 导出Schema用于运行时验证
export const UserSchema = userSchema;

这样Typedoc会将User类型展示为展开后的TS结构，而非原始的z.infer表达式。

2. 使用Typedoc Zod插件自动转换类型格式 #

专门的typedoc-plugin-zod插件可以自动解析Zod类型，将ZodObject、ZodOptional等转换为TS原生格式，同时修正可选属性的显示：

安装插件：

npm install typedoc-plugin-zod --save-dev

在typedoc.json中配置插件：

{
  "plugins": ["typedoc-plugin-zod"]
}

插件会自动把ZodObject<{ name: ZodOptional<ZodString>}>转换成{ name?: string }，并将undefined | string格式的可选属性改为name?: string，完全贴合手写TS类型的文档效果。

3. 手动关联类型与Schema（精细控制场景） #

如果需要更精细的文档控制，可以手动定义类型结构，同时通过TypeOf工具类型关联Zod Schema，保证类型一致性：

import { z, TypeOf } from 'zod';

const userSchema = z.object({
  name: z.string().optional(),
  age: z.number()
});

/**
 * 用户信息类型
 * @property name - 用户名称（可选）
 * @property age - 用户年龄
 */
export type User = {
  name?: string;
  age: number;
} & TypeOf<typeof userSchema>;

export const UserSchema = userSchema;

& TypeOf<typeof userSchema>会强制手动定义的类型与Schema对齐，避免不一致，同时Typedoc会优先展示手动定义的清晰结构。

4. 开启Typedoc的类型展开配置 #

在typedoc.json中设置"expand": true，可以让Typedoc自动展开z.infer生成的类型，无需额外修改代码：

{
  "expand": true
}

结合给Schema添加的JSDoc注释，就能生成更清晰的文档。

1. Typedoc Zod插件：最省心，零手动修改，直接解决所有三个问题；
2. @typedef注释+类型展开：无需额外依赖，配置简单；
3. 手动类型关联：适合需要高度定制文档的场景。

内容的提问来源于stack exchange，提问作者Shawn