vitepress-plugin-md-api

在 VitePress 的 Markdown 中使用 @API('类型文件', '接口名')，自动把 TypeScript interface / type 渲染为接口说明表格。

生成的表格支持 必填、默认值、废弃标记、readonly、方法签名、索引签名、JSDoc 注释，并内置 多语言（zh-CN / en-US），可扩展任意语言。

✨ 特性

• 🧩 一行指令 @API('../types/user.ts', 'User') 即生成 API 表格
• 🟢 支持 .vue 文件：自动提取 <script lang="ts"> / <script setup lang="ts"> 中的 interface / type（含跨 .vue 文件 import 继承）
• 🔗 自动识别继承：interface A extends B、多继承、跨文件 import 继承、type X = A & B 交叉类型，父级字段自动合并（子接口字段在前、同名覆盖以子接口为准）
• 📐 联合类型 A | B 中的管道符自动转义，不会撑坏表格列
• 🧱 Vue Props 类型自动标准化：BooleanConstructor → boolean、PropType<T> → T、{ type, default, required } 定义对象自动提取真实类型/默认值/必填性、import("pkg").X 自动去前缀（ant-design-vue / element-plus 等组件库 props 直接可读）
• 🔍 基于 TypeScript 编译器 API（TypeChecker）解析 AST，类型/方法/索引签名准确还原
• 📝 自动提取 JSDoc：说明、@default 默认值、@deprecated 废弃原因
• 🌐 内置 zh-CN / en-US 界面文案，JSDoc 用 @locale 标签做多语言注释
• 🗂️ 与 VitePress locales 目录结构联动，按路径自动切换语言
• ⚠️ 解析失败时输出警告块，不中断构建
• 🔥 通过 addWatchFile 监听类型文件，修改后文档热更新
• 🛡️ 代码块内的 @API(...) 示例自动遮蔽，不会被误替换

📦 安装

npm i -D vitepress-plugin-md-api
# pnpm add -D vitepress-plugin-md-api
# yarn add -D vitepress-plugin-md-api

🚀 快速开始

1. 注册插件

在 .vitepress/config.mts 中挂载：

import { defineConfig } from 'vitepress'
import { mdApiPlugin } from 'vitepress-plugin-md-api'

export default defineConfig({
  vite: {
    plugins: [mdApiPlugin()]
  }
})

2. 准备类型文件

// types/user.ts
export interface User {
  /** 用户名 */
  name: string
  /** 年龄 @default 18 */
  age?: number
  /** @deprecated 请使用 name */
  oldName?: string
  readonly id: string
  /** 打招呼 */
  greet(greeting: string, loud?: boolean): string
  [key: string]: any
}

3. 在 Markdown 中使用

@API('../types/user.ts', 'User')

渲染结果：

| 属性名 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | name | string | 是 | - | 用户名 | | age | number | 否 | 18 | 年龄 | | oldName | string | 否 | - | （已废弃：请使用 name） | | id (readonly) | string | 是 | - | - | | greet(greeting: string, loud?: boolean) | string | 是 | - | 打招呼 | | [key: string] | any | 是 | - | - |

类型文件路径相对当前 markdown 文件解析，省略扩展名时会自动尝试 .ts / .d.ts / .tsx / .mts / .cts / .vue。

直接引用 Vue 组件中的类型

.vue 单文件组件同样支持，插件会提取 <script lang="ts"> 与 <script setup lang="ts"> 两个块中的类型定义：

@API('./components/Pagination.vue', 'PaginationProps')

<!-- components/Pagination.vue -->
<script setup lang="ts">
interface PaginationProps {
  /** 组件尺寸 */
  size?: 'default' | 'small'
  /** 是否禁用 */
  disabled?: boolean
}
defineProps<PaginationProps>()
</script>

引用组件库导出的运行时 props 类型（如 ant-design-vue 的 ButtonProps）时，类型会自动标准化：

| 源码类型 | 表格显示 | | --- | --- | | StringConstructor / BooleanConstructor | string / boolean | | PropType<ButtonType> | ButtonType | | { type: BooleanConstructor; default: any } | boolean | | { type: StringConstructor; default: 'small' } | 类型 string，默认值列填 "small" | | { type: [StringConstructor, NumberConstructor] } | string \| number | | import("vue-types").VueTypeValidableDef<any> | any |

默认值仅在类型可静态确定（字面量或返回字面量的工厂函数 () => false）时提取；default: any 这类无法确定具体值的情况默认值列仍显示 -。required: true/false 会覆盖必填列。

继承接口自动合并

父接口（包括通过 import 引入的跨文件父接口、多继承、交叉类型）的成员会自动展开到表格中：

// types/base.ts
export interface BaseEntity {
  /** 主键 ID */
  id: string
}

// types/user.ts
import type { BaseEntity } from './base'

export interface User extends BaseEntity {
  /** 用户名 */
  name: string
}
// 等价于表格包含 id + name 两个字段

🌐 多语言支持

指令显式指定

第三个参数为语言代码：

@API('../types/user.ts', 'User', 'en-US')

JSDoc 多语言注释

在类型文件中用 @locale <语言代码> <说明> 提供翻译，未命中的语言回退到默认注释：

export interface Book {
  /**
   * 书名
   * @locale en-US Book title
   * @locale ja-JP 書名
   */
  title: string
}

废弃原因同理：@deprecatedLocale en-US Use name instead。

语言判定优先级

1. 指令第三参数（支持前缀匹配，en 可命中 en-US）
2. Markdown 文件路径前缀检测（VitePress locales 目录如 doc/en/）
3. 插件选项 defaultLocale（默认 zh-CN）

自定义语言包

通过 locales 选项扩展或覆盖语言包，只写需要覆盖的字段，其余回退内置文案：

mdApiPlugin({
  defaultLocale: 'zh-CN',
  locales: {
    'ja-JP': {
      columnName: 'プロパティ',
      columnType: '型',
      columnRequired: '必須',
      columnDefault: 'デフォルト',
      columnDescription: '説明',
      yes: 'はい',
      no: 'いいえ',
      readonlyLabel: 'readonly',
      deprecated: (r) => `**（非推奨${r ? `：${r}` : ''}）**`,
      noProperties: (n) => `\`${n}\` にプロパティがありません`,
      parseFailed: '解析失敗：'
    }
  }
})

LocaleMessages 完整字段：

| 字段 | 类型 | 说明 | | --- | --- | --- | | columnName | string | 表头「属性名」 | | columnType | string | 表头「类型」 | | columnRequired | string | 表头「必填」 | | columnDefault | string | 表头「默认值」 | | columnDescription | string | 表头「说明」 | | yes / no | string | 是 / 否 | | readonlyLabel | string | readonly 标记文本 | | deprecated | (reason?: string) => string | 废弃标记 | | noProperties | (name: string) => string | 空接口提示 | | parseFailed | string | 解析失败警告块标题 |

⚙️ 插件选项

interface MdApiPluginOptions {
  /** 类型文件解析基准目录（绝对路径），默认先相对当前 md 目录再回退到此目录 */
  baseDir?: string
  /** 默认界面语言代码，默认 `zh-CN` */
  defaultLocale?: string
  /** 自定义 / 覆盖语言包，key 为语言代码，value 为部分或完整 LocaleMessages */
  locales?: Record<string, Partial<LocaleMessages>>
}

🏗️ 开发 & 发布

# 构建
npm run build          # tsc 输出到 dist/

# 本地测试发布
npm pack

# 发布到 npm
npm publish

📄 License

MIT