前端组件库 API 文档自动化：基于 react-docgen-typescript 与 AST 的落地踩坑实践

// src/components/Button/Button.tsx
import React from 'react';

export interface ButtonProps {
  /** 按钮的样式变体 */
  variant?: 'primary' | 'secondary' | 'danger';
  /** 是否处于加载中状态 */
  loading?: boolean;
  /** 点击事件回调 */
  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
  /** 子节点内容 */
  children: React.ReactNode;
}

/**
 * 通用按钮组件，支持多种业务状态。
 */
export const Button: React.FC<ButtonProps> = ({
  variant = 'primary',
  loading = false,
  children,
  onClick,
}) => {
  return (
    <button className={`btn btn-${variant}`} onClick={onClick} disabled={loading}>
      {children}
    </button>
  );
};

// scripts/extract-api.ts
import * as path from 'path';
import * as docgen from 'react-docgen-typescript';

const tsconfigPath = path.resolve(__dirname, '../tsconfig.json');

// 创建解析器
const parser = docgen.withCustomConfig(tsconfigPath, {
  savePropValueAsString: true,
  shouldExtractLiteralValuesFromEnum: true, // 提取联合类型的具体字面量
});

const componentPath = path.resolve(__dirname, '../src/components/Button/Button.tsx');
const docs = parser.parse(componentPath);

console.log(JSON.stringify(docs, null, 2));

export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'primary' | 'secondary';
}

const parser = docgen.withCustomConfig(tsconfigPath, {
  propFilter: (prop, component) => {
    if (prop.declarations !== undefined && prop.declarations.length > 0) {
      // 检查属性声明是否来自 node_modules
      const isFromNodeModules = prop.declarations.some((declaration) => {
        return declaration.fileName.includes('node_modules');
      });
      return !isFromNodeModules;
    }
    return true;
  },
});

export type Size = 'small' | 'medium' | 'large';

export interface CardProps {
  size?: Size;
}

"size": {
  "type": {
    "name": "enum",
    "value": [
      { "value": "\"small\"" },
      { "value": "\"medium\"" },
      { "value": "\"large\"" }
    ]
  }
}

export const Input = React.forwardRef<HTMLInputElement, InputProps>((props, ref) => {
  return <input ref={ref} {...props} />;
});

import { Project, SyntaxKind } from 'ts-morph';

function fixComponentDisplayName(filePath: string, defaultName: string): string {
  const project = new Project();
  const sourceFile = project.addSourceFileAtPath(filePath);

  // 查找 export const xxx = ...
  const exportDeclarations = sourceFile.getVariableStatements()
    .filter(statement => statement.isExported());

  for (const statement of exportDeclarations) {
    for (const decl of statement.getDeclarationList().getDeclarations()) {
      const initializer = decl.getInitializer();
      // 如果包含 forwardRef 调用，直接拿变量名作为组件名
      if (initializer && initializer.getText().includes('forwardRef')) {
        return decl.getName();
      }
    }
  }

  return defaultName;
}