自动生成组件 API 文档指南

本指南介绍如何使用 react-docgen-typescript 自动从 TypeScript React 组件中提取 API 文档。

概述

我们已经设置了一个自动化系统来:

1. ✅ 扫描所有 ui-core 组件
2. ✅ 提取 props、类型、默认值和描述
3. ✅ 生成 Vue 组件用于文档展示
4. ✅ 生成 JSON 文件用于其他用途

快速开始

1. 生成 API 文档

运行以下命令来生成所有组件的 API 文档:

pnpm --filter @xcloud/docs generate:api

这将:

• 扫描 packages/ui-core/src/components 中的所有 .tsx 文件
• 为每个组件生成一个 Vue 组件 (如 ButtonRootApi.vue)
• 生成一个包含所有组件 API 的 JSON 文件

2. 在文档中使用

在你的 markdown 文件中导入并使用生成的 API 组件:

<script setup>
import ButtonDemo from '../../demos/button-basic.tsx'
import ButtonDemoSource from '../../demos/button-basic.tsx?raw'
import CodePreview from '../../.vitepress/theme/components/CodePreview.vue'
import ButtonRootApi from '../../.vitepress/theme/api/ButtonRootApi.vue'
</script>

<!-- 组件预览 -->
<CodePreview :component="ButtonDemo" :source="ButtonDemoSource" />

<!-- API 文档表格 -->
<ButtonRootApi />

输出内容

1. Vue 组件 (.vitepress/theme/api/*.vue)

每个组件都会生成一个对应的 Vue 文件，包含:

• 自动格式化的 API 表格
• 主题适配的样式
• 可以直接在 markdown 中使用

示例: ButtonRootApi.vue 会显示 ButtonRoot 组件的所有 props。

2. JSON 文件 (.vitepress/theme/api/components-api.json)

包含所有组件的完整 API 数据，可用于:

• 搜索功能
• API 索引页面
• 其他自动化工具

JSON 结构:

{
  "ButtonRoot": {
    "name": "ButtonRoot",
    "description": "按钮组件",
    "props": {
      "variant": {
        "type": "'primary' | 'secondary'",
        "required": false,
        "defaultValue": "'primary'",
        "description": "按钮样式变体"
      }
    }
  }
}

为组件添加文档注释

为了生成更好的 API 文档，请在组件代码中添加 JSDoc 注释:

interface ButtonProps {
  /**
   * 按钮样式变体
   * @default 'primary'
   */
  variant?: 'primary' | 'secondary' | 'neutral'

  /**
   * 按钮大小
   */
  size?: 'small' | 'medium' | 'large'

  /**
   * 是否禁用按钮
   */
  disabled?: boolean

  /**
   * 点击事件处理器
   */
  onClick?: () => void
}

/**
 * 按钮组件 - 用于用户交互
 *
 * @example
 * ```tsx
 * <Button variant="primary" size="medium">
 *   点击我
 * </Button>
 * ```
 */
export function ButtonRoot({ variant = 'primary', ...props }: ButtonProps) {
  // ...
}

生成的文档将包含这些描述!

配置选项

脚本位于 packages/docs/scripts/generate-api-components.mjs。

你可以修改以下配置:

// 组件源码目录
const COMPONENTS_DIR = path.resolve(__dirname, '../../ui-core/src/components')

// 输出目录
const OUTPUT_DIR = path.resolve(__dirname, '../.vitepress/theme/api')

// 解析器选项
const parserOptions = {
  shouldExtractLiteralValuesFromEnum: true,  // 提取枚举值
  shouldRemoveUndefinedFromOptional: true,   // 移除可选 prop 的 undefined
  propFilter: (prop) => {
    // 过滤不需要的 props
  }
}

高级用法

1. 只生成特定组件

修改脚本来只处理特定文件:

const files = fs.readdirSync(COMPONENTS_DIR)
  .filter(file => file === 'button.tsx') // 只处理 button.tsx
  .map(file => path.join(COMPONENTS_DIR, file))

2. 自定义表格样式

修改生成的 Vue 组件模板中的样式:

function generateApiComponent(componentDoc) {
  // ...自定义模板...
}

3. 添加更多信息

可以提取更多信息，如:

• 方法 (methods)
• 事件 (events)
• 插槽 (slots)

工作流程

graph LR
    A[TypeScript 组件] -->|react-docgen-typescript| B[解析 Props]
    B --> C[生成 Vue 组件]
    B --> D[生成 JSON]
    C --> E[Markdown 文档]
    D --> F[搜索/索引]

集成到 CI/CD

在构建前自动生成

修改 packages/docs/package.json:

{
  "scripts": {
    "prebuild": "pnpm generate:api",
    "build": "vitepress build"
  }
}

Git Hook

在提交前自动生成:

# .husky/pre-commit
pnpm --filter @xcloud/docs generate:api
git add packages/docs/.vitepress/theme/api/

示例

完整的组件文档模板

# Button 按钮

交互式按钮组件。

## 导入

\`\`\`tsx
import { Button } from '@xcloud/ui-core'
\`\`\`

## 示例

<script setup>
import ButtonDemo from '../../demos/button-basic.tsx'
import ButtonDemoSource from '../../demos/button-basic.tsx?raw'
import CodePreview from '../../.vitepress/theme/components/CodePreview.vue'
import ButtonRootApi from '../../.vitepress/theme/api/ButtonRootApi.vue'
</script>

<CodePreview :component="ButtonDemo" :source="ButtonDemoSource" />

## 基础用法

\`\`\`tsx
<Button.Root variant="primary">
  点击我
</Button.Root>
\`\`\`

## API

<ButtonRootApi />

## 功能特性

- ✅ 多种样式变体
- ✅ 响应式设计
- ✅ 无障碍访问

常见问题

Q: 为什么某些组件没有生成 props?

A: 可能是因为:

1. 组件没有定义 TypeScript 接口
2. Props 被 propFilter 过滤掉了
3. 组件使用了动态 props

解决方法: 为组件添加明确的 TypeScript 类型定义。

Q: 如何显示继承的 props?

A: 修改 propFilter 函数:

propFilter: (prop) => {
  return true  // 显示所有 props，包括继承的
}

Q: 能否生成 Markdown 表格而不是 Vue 组件?

A: 可以！修改 generateApiComponent 函数直接返回 Markdown 字符串，并保存为 .md 文件。

Q: 支持其他组件库格式吗?

A: 支持！react-docgen-typescript 可以解析任何 TypeScript React 组件。

其他工具推荐

如果你需要更多功能，可以考虑:

1. Storybook - 完整的组件开发环境
2. Docusaurus - 功能丰富的文档系统
3. react-docgen - 适用于 JavaScript 组件
4. typedoc - 适用于 TypeScript 库

总结

使用自动 API 文档生成:

优势:

• ✅ 减少手动维护
• ✅ 保持文档与代码同步
• ✅ 提取 TypeScript 类型信息
• ✅ 自动生成标准化格式

流程:

1. 编写带 JSDoc 的组件
2. 运行 pnpm generate:api
3. 在文档中导入生成的 API 组件
4. 提交到版本控制

结果:

• 📦 169 个组件的 API 文档自动生成
• 🎨 统一的表格样式
• 🔍 可搜索的 JSON 数据
• 📝 易于维护的文档

开始使用吧！🚀