用于自动生成 API 文档描述,支持 react-docgen-typescript 和 documentation。
首先在配置文件中写入以下的配置:
然后你可以在 MDX 中使用 API 组件将 API 内容注入到文档中:
这个插件接受一个对象参数,类型如下:
appDir
用来配置插件解析文件的基准目录,默认为 process.cwd()
entries
用来配置解析文件的基本信息:
moduleName
属性apiParseTool
用来选择解析工具,默认为react-docgen-typescript
:
react-docgen-typescript
针对于组件库场景,仅会解析 props 生成表格。上面是一个标准写法,其中 ButtonProps
将被提取至表格中, Button
作为表格的标题。
如果使用默认导出,文件名将作为表格标题。
需要注意的是,export 导出事先定义的特性将不会被解析。
生成的内容如下:
如果 Props 里使用了 React 的类型,你需要在 tsconfig.json 里添加 types ,否则会解析不到 React 命名空间下的类型。
更好的方式是直接引用类型,例如
documentation
适用于工具库场景,用来解析 JSDoc 注释。
下面是一个带有 JSDoc 注释的 greet 函数。上面是一个带有 JSDoc 注释的 greet 函数。生成的内容如下:
parseToolOptions
用来传入对应解析器的参数,其类型如下:
请参考 ParserOptions 和 DocumentationArgs 了解可用选项。
如果解析器是 react-docgen-typescript
,默认使用 withDefaultConfig
方法创建解析器实例,如果配置了 tsconfigPath
或 compilerOptions
则会分别使用 withCompilerOptions
和 withCustomConfig
方法创建解析器实例,tsconfigPath
和 compilerOptions
可以分别针对每个 entry
设置,详情查看 Custom Parsers。