写组件文档写到吐？我用AI自动生成Storybook，同事以后直接抄

kyriewen
0 阅读5分钟

我们公司的组件库有一百多个组件，但文档几乎为零。新同事来了，不知道每个组件怎么用、支持哪些props，只能翻源码。我每周至少被问三次：“这个按钮的size参数是‘large’还是‘lg’？” 我烦了，写了个脚本：用AI读取组件的TypeScript类型定义，自动生成Storybook文档和示例代码。现在每次提交组件，CI自动跑一遍，文档实时更新。同事再也不问我了，CTO看到说：“这个自动化做得好，省了半个前端的人力。”

前言

组件文档的重要性，每个前端都懂。但现实是：业务需求压过来，谁有时间写文档？结果就是组件库越来越膨胀，文档越来越荒废。新人来了，要么猜，要么问，要么翻源码。

我试过手动写Storybook，一个组件写半小时，一百个组件写完，我可能已经离职了。后来我想：能不能让AI自动生成？组件的props类型、默认值、描述，不都写在代码里了吗？让AI提取出来，再套个模板，不就完事了？

今天我把这套自动化流程拆给你看：怎么用AI解析TS类型，怎么生成Storybook的stories文件，怎么集成到CI。以后你只需要写好组件，文档的事交给AI。

金句：最好的文档不是“人写的”，而是“代码里长出来的”。

一、痛点：手动写文档的三大坑

痛点具体表现
耗时长一个组件平均花30分钟写文档（props表格+示例代码+说明）
不同步改了组件props，忘了改文档，文档变成“废纸”
没人愿意写团队集体拖延，文档库永远是“建设中”

我们团队曾试图用react-docgen-typescript自动提取props，但它只能生成原始JSON，还得人工转成Markdown或Storybook。而且它不懂业务描述，比如“size的large表示大号按钮，用于主操作”，这种描述还是得人写。

AI的出现正好填补了这个缺口：它既能解析类型，又能生成自然语言描述，还能帮你写示例代码。

二、我是怎么做的？三步全自动

第一步：提取组件类型信息

我用react-docgen-typescript把组件的props、类型、默认值、是否必填提取成JSON。写一个脚本extract-props.ts：

import * as docgen from 'react-docgen-typescript';

const options = {
  savePropValueAsString: true,
  shouldExtractLiteralValuesFromEnum: true,
};

const parser = docgen.withCustomConfig('./tsconfig.json', options);
const docs = parser.parse('./src/components/Button/index.tsx');

// docs[0] 结构：
// {
//   displayName: 'Button',
//   props: {
//     size: { type: { name: "'small' | 'medium' | 'large'" }, required: false, defaultValue: 'medium' },
//     children: { type: { name: 'ReactNode' }, required: true }
//   }
// }

第二步：用AI生成Storybook内容

把提取的JSON喂给AI，提示词：

你是一名前端技术文档专家。请根据以下组件的props信息，生成一份Storybook的stories文件代码。

要求：

  1. 为每个prop生成控制台（controls）配置
  2. 生成至少3个示例：基础用法、不同尺寸、自定义样式
  3. 用Markdown格式输出，包含组件描述和Props表格

组件信息：

[粘贴上一步的JSON]

AI会输出类似这样的Storybook代码：

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  parameters: {
    docs: {
      description: {
        component: '通用按钮组件，支持三种尺寸和两种主题色。主要用于表单提交、弹窗确认等操作。'
      }
    }
  },
  argTypes: {
    size: {
      control: 'radio',
      options: ['small', 'medium', 'large'],
      description: '按钮尺寸'
    },
    children: { control: 'text', description: '按钮内容' }
  }
};

export default meta;

export const Default: StoryObj<typeof Button> = {
  args: { children: '按钮', size: 'medium' },
};

export const Large: StoryObj<typeof Button> = {
  args: { children: '大按钮', size: 'large' },
};

export const Small: StoryObj<typeof Button> = {
  args: { children: '小按钮', size: 'small' },
};

第三步：集成到CI

我在项目的.github/workflows/docs.yml里加了一个job：

- name: Auto generate Storybook
  run: |
    npm run extract:props
    npm run ai:generate-stories
    npm run build:storybook
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

每次git push到main分支，GitHub Actions自动跑一遍，重新生成文档并部署到GitHub Pages。从此文档永远最新。

金句：AI自动生成文档，让“文档过时”成为历史。

三、实测效果：节省了多少时间？

我们组件库有87个组件，人工写一个平均30分钟，总计43.5小时。用AI自动生成后，每个组件约2分钟（人工review和微调），总计约3小时。节省了93%的时间。

指标手工AI辅助变化
单组件文档耗时30分钟2分钟↓ 93%
文档与代码同步率经常滞后实时同步-
新人上手询问次数（月均）12次2次↓ 83%

同事现在想查组件用法，直接打开Storybook。没人再问我了，我可以安心写代码。

四、注意事项（坑点）

  • AI会脑补不存在的props：有时会生成示例里用了你没提供的prop，必须人工删掉。
  • 复杂泛型可能解析错：react-docgen-typescript对高阶组件、泛型组件的解析不够准，需要手动修正输入JSON。
  • 保护公司组件库隐私：不要直接把整个组件库代码喂给云端AI。可以用本地模型（如Ollama + CodeLlama），或者只传类型JSON（不传实现细节）。
  • 示例代码要人工跑一遍：AI生成的示例可能无法直接运行（比如忘记import样式），你至少编译一次确保没语法错误。

五、完整的Prompt模板（复制可用）

# 角色
你是一名前端技术文档专家，擅长为React组件生成Storybook文档。

# 任务
根据以下组件的props信息，生成一个完整的Storybook stories文件。

# 输入格式
JSON对象，包含displayName和props

# 输出要求
1. 使用TypeScript语法
2. 包含meta配置（title, component, parameters, argTypes）
3. 生成至少3个Story：Default, Large, Small（或其他合适的变体）
4. 在parameters.docs.description.component中写一段组件用途说明
5. 每个argType的control要合理（radio/select/text等）

# 组件信息
[粘贴JSON]

六、写在最后

以前我觉得文档是“良心活”，写了加分，不写也没人扣分。现在AI帮我自动生成，我才发现：文档不是负担，而是杠杆——它让组件的复用率大大提升，团队效率自然就上去了。

如果你也被组件文档折磨过，或者想知道怎么把AI接入你的工程化流程，点个赞让我看到。

avatar
文章
阅读
粉丝