随着前端开发的快速发展，模块化已经成为了几乎每个项目的必需品。在面对大量的模块代码时，我们需要工具来帮助我们自动生成类型定义文件（TypeScript）和 API 文档。在这篇文章中，我们将介绍一个非常好用的 npm 包：extract-typedefs。
extract-typedefs 概述
extract-typedefs 是一个用于生成 TypeScript 类型定义文件的工具，它的主要特点是自动解析 JavaScript 源代码中的类型信息（包括 JSDoc 注释），以生成 TypeScript 的类型定义文件。
extract-typedefs 可读取 JavaScript 文件或 TypeScript 文件，生成对应的 TypeScript 类型定义文件。在自动生成类型定义文件的同时，它还可以生成方便的 API 文档。
安装
使用以下命令可以安装 extract-typedefs ：
--- ------- -- ------------------------ ----------
命令解释：
-D表示将包安装到开发依赖里；@microsoft/api-extractor是用于生成 API 文档的核心包；typescript是用于编译 TypeScript 代码的包。
使用方法
简单使用
在安装好 extract-typedefs 后，我们就可以使用它来生成 TypeScript 类型定义文件和 API 文档了。
假设我们要生成的 TypeScript 类型定义文件名为 mytype.d.ts，那么命令如下：
--- ---------------- -------- -------- -- -----------
file1.js、file2.js为需要生成类型定义文件的源文件；-o表示输出路径，跟在后面的是输出的目标路径与文件名。
执行上述命令后，mytype.d.ts 就会生成了。
指定构建配置
extract-typedefs 也可以在项目中配置构建规则，具体方法如下：
- 在项目根目录下新建
api-extractor.json配置文件：
-
---------- ------------------------------------------------------------------------------------------
------------------------- -------------------
----------- -
---------- ----
--
------------ ---
------------ -
---------- -----
----------------- --------------------
-
-其中：
mainEntryPointFilePath是类型文件所在的目标路径（相对路径或绝对路径均可）；docModel表示生成 API 文档；apiReport表示生成 Markdown 格式的 API 文档。
- 修改项目的
package.json，增加如下代码：
-
---------- -
------ -------------- --- ------- -----------
---------- ---- --- --- -- ----
-
-这里的 doc 和 prepare 命令就是配置文件所提到的 API 文档生成命令和 TypeScript 编译命令。
现在，我们就可以在项目根目录中使用 npm run prepare 命令，自动编译 TypeScript，并生成 API 文档了。
示例代码
我们可以使用一个示例代码来演示如何使用 extract-typedefs。
示例代码目录结构如下：
------- --- ------------------ --- --- - --- -------- - --- -------- --- ----------------- --- ------------ --- -------------
其中，index.ts 如下所示：
------ - ---- ----------
greet.ts 如下所示：
--- - ------- -- ------ -------- ----------- -------- ------ - ------ ------- ---------- -
配置文件（api-extractor.json）如下所示：
-
---------- ------------------------------------------------------------------------------------------
------------------------- -------------------
----------- -
---------- ----
--
------------ ---
------------ -
---------- -----
----------------- --------------------
-
-执行命令后，可以得到如下目录结构：
-------
--- ------------------
--- ---
- --- --------
- --- --------
--- -----------------
--- ------------
--- -------
- --- --------
--- -------------
--- -----
--- ----------mylib.md 如下所示：
- --- ------ -- --------- --- ----- ------------- ------ ------- -------- ----------- -------- -------
Public function.
Parameters
| Name | Type | Description |
|---|---|---|
name |
string | The person to greet. |
Returns
Type: string
Version Information
| Property | Value |
|---|---|
npmPackageName |
example |
npmPackageVersion |
1.0.0 |
generatedBy |
@microsoft/api-extractor |
ℹ️ API Extractor found 1 warning(s)!
----- ---------- ---------- --- --- -- -- ------------------ ------------------------- ---------- ------- --- ---------------------------------- ------------------------------------------------------------------------------ ---------- -----------------------------------------------------------------------------------------------------------------------------