# @alifd/api-extractor

> A tool to help extracting api from React components.

Latest version **3.7.2** (published 2021-06-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @alifd/api-extractor
pnpm add @alifd/api-extractor
yarn add @alifd/api-extractor
bun add @alifd/api-extractor
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.7.2 |
| Published | 2021-06-11 |
| First published | 2018-08-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 24.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 18 |
| Maintainers | no-repeat, wwsun, aboutblank, bindoon, tao1991123, vicerwang, myronliu347, jdkahn, fusion-bot, sobear, lianmin, clarkxia, quanyin, jerryyxu, yellow2dong, alvinhui, andevery, luhengchang228, chenbin93, yuysmile, fd.xy |
| Keywords | react, api, doc, fusion, next |

## Links

- npm: https://www.npmjs.com/package/@alifd/api-extractor
- Repository: https://github.com/alibaba-fusion/api-extractor
- Issues: https://github.com/alibaba-fusion/api-extractor/issues
- npm.io page: https://npm.io/package/@alifd/api-extractor

## Dependencies (5)

- [glob](https://npm.io/package/glob.md) ^7.1.2
- [doctrine](https://npm.io/package/doctrine.md) ^2.0.0
- [react-docgen](https://npm.io/package/react-docgen.md) ^2.17.0
- [@babel/parser](https://npm.io/package/@babel/parser.md) 7.x
- [@babel/traverse](https://npm.io/package/@babel/traverse.md) 7.x

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 3.7.2 (latest) — 2021-06-11
- 3.6.0-beta (beta) — 2019-11-14
- 3.5.3 — 2020-12-16
- 3.7.1 — 2020-11-16
- 3.7.0 — 2020-01-14
- 3.6.0 — 2019-11-14
- 3.5.2 — 2019-08-12
- 3.5.1 — 2019-07-23
- 3.5.0 — 2019-01-09
- 3.4.2 — 2018-12-19
- 3.4.1 — 2018-12-19
- 3.4.0 — 2018-12-19
- 3.3.2 — 2018-09-03
- 3.3.1 — 2018-08-22
- 3.3.0 — 2018-08-22

## README

# @alifd/api-extractor
一个从 React 组件代码中提取 API 信息的工具，一般用来生成 API 文档，开发编辑器组件 API 提示插件以及开发页面搭建平台组件物料的属性面板，代码中附加信息书写方式来源于[jsDoc](http://usejsdoc.org/)，整体底层解析工具依赖于 [react-docgen](https://github.com/reactjs/react-docgen) 和 [doctrine](https://github.com/eslint/doctrine)。

[![npm package](https://img.shields.io/npm/v/@alifd/api-extractor.svg?style=flat-square)](https://www.npmjs.org/package/@alifd/api-extractor)

## Feature
* 支持通过`propTypes`获得属性类型
* 支持通过`defaultProps`获得属性默认值
* 支持通过`propTypes`上的 jsDoc 注释获得属性描述，自定义属性默认值
* 支持通过书写 jsDoc 获取函数类型属性的参数和返回值
* 支持通过书写 jsDoc 获取对象类型属性的属性
* 支持通过书写 jsDoc 获取组件静态方法和实例方法的描述，参数以及返回值
* 支持根据提取的 API 信息生成 markdown 片段，方便灵活组织API文档
* 支持通过按照约定书写组件上的 jsDoc 来获得父组件与子组件关系
* 支持通过`propTypes = {...Base.propTypes}`的方式扩展

## Install

```
npm install @alifd/api-extractor
```

## Usage

``` js
const extractor = require('@alifd/api-extractor');
const apiInfo = extractor.extract(componentDirPath);
// const apiInfo = extractor.extractFile(componentFilePath);
```

## API

### extract(componentDirPath, options, parentMap)
**参数**：

* componentDirPath `String` 组件代码文件夹路径
* options `Object` 可选项
  * md `Boolean` 是否生成`props`和`method`的 markdown 片段，默认值为`false`
  * fileErrorHandler `Function` 自定义单个文件的错误处理函数，默认直接抛出错误
* parentMap `Object` 可选项 组件继承关系，例如 Nav 继承自 Menu ，通过该参数可将 Menu 上的props merge到 Nav上
```js
{
  'Nav': {
    name: 'Menu',
    path: 'my-path/src/menu'
  },
  'Nav.Item': {
    name: 'Menu.Item',
    path: 'my-path/src/menu'
  }
}
```

**返回值**：

`Object` 参考下方 Example

### extractFile(componentFilePath, options)
**参数**：

* componentFilePath `String` 组件代码文件路径
* options `Object` 可选项
  * md `Boolean` 是否生成`props`和`method`的 markdown 片段，默认值为`false`

**返回值**：

`Object` 参考下方 Example

### generatePropsMD(props)
**参数**：

* props `Object` 使用`extract`方法生成api信息的`props`属性

**返回值**：

`String` props对应的markdown文本

### generateMethodMD(method)
**参数**：

* method `Object` 使用`extract`方法生成api信息的`methods`属性的Item

**返回值**：

`String` method对应的markdown文本

## Example

如果传入的组件代码根路径下存在以下两个文件：

menu.js

``` js
import React, { Component} from 'react';
import PropTypes from 'prop-types';

/**
 * Menu
 **/
export default class Menu extends Component {
  static propTypes = {
    /**
     * the menu size
     **/
    size: PropTypes.string,
    /**
     * select menu callback
     * @param {Array} selectedKeys the seleced keys
     **/
    onSelect: PropTypes.func
  };

  static defaultProps = {
    size: 'medium',
    onSelect: () => {}
  };

  render() {
    // ...
  }
}
```

menu-item.js

``` js
import React, { Component} from 'react';
import PropTypes from 'prop-types';

/**
 * Menu.Item
 **/
export default class Item extends Component {
  // ...
}
```

我们会得到如下的 json 结构：

``` js
{
  "name": "Menu",                              // 组件名
  "props": {
    "size": {                                  // 属性名
      "type": {
        "name": "string"                       // 属性类型
      },
      "required": false,                       // 属性是否必需
      "description": "the menu size",          // 属性描述
      "defaultValue": {
        "value": "'medium'",                   // 属性默认值
        "computed": false
      }
    },
    "onSelect": {
      "type": {
        "name": "func"
      },
      "required": false,
      "description": "select menu callback",
      "defaultValue": {
        "value": "() => {}",
        "computed": false
      },
      "docblock": "select menu callback\n@param {Array} selectedKeys the seleced keys",
      "params": [                               // 函数参数
        {
          "name": "selectedKeys",               // 函数参数名
          "description": "the seleced keys",    // 函数参数描述
          "type": {
            "name": "Array"                     // 函数参数类型
          }
        }
      ],
      "returns": null                           // 函数返回值
    }
  },
  "propsMD": "...",                             // 开启了md参数后，所有属性渲染出的 Markdown 文件
  "methods": [],                                // 方法
  "subComponents": [                            // 子组件
    {
      "description": "Item",
      // ...
    }
  ]
}
```

该 json 结构在[react-docgen 生成的 json 结构](https://github.com/reactjs/react-docgen#proptypes)基础上扩展而成。主要增加了`subComponents`，`propsMD`，属性为函数时的`parmas`，`return`和属性为对象时的`properties`结构。

`propsMD` 属性一般用来生成README.md中的API文档，`Menu` 组件的 `propsMD` 具体如下所示：

```
参数 | 说明 | 类型 | 默认值
-----|-----|-----|-----
size | the menu size | String | 'medium'
onSelect | select menu callback<br><br>**签名**:<br>Function(selectedKeys: Array) => void<br>**参数**:<br>selectedKeys {Array} the seleced keys | Function | () => {}
```

## Note
1. 只有添加了 jsDoc 注释的组件类，组件的属性以及组件的方法，才会被工具提取出相应的 API 信息。

2. 只有在文件中被`export default`的组件类才会被提取 API 信息

3. 默认传入的组件路径下只有一个根组件，如果想对外暴露两个组件，如`Row`和`Col`，也请在 jsDoc 的注释中添加根组件的前缀，如`Grid.Row`和`Grid.Col`。

4. 如果想控制子组件在`subComponents`中出现的顺序，以方便生成对应的 API 文档，可以为组件类的 jsDoc 注释中添加`order`字段（默认按照首字母顺序排列），如下所示：

      row.js
      ``` js
      /**
       * Grid.Row
       * @order 1
       */
      export default class Row extends Component {
        // ...
      }
      ```

      col.js

      ``` js
      /**
       * Grid.Col
       * @order 2
       */
      export default class Col extends Component {
        // ...
      }
      ```

5. 工具只支持一层的子组件，也就是说无法处理`AAA.BBB.CCC`的情况，当然我们也不认为这是一个组件应该对外暴露的使用方式。

6. 如果想自定义属性默认值，可以采用下面方法（其优先级高于`defaultProps`）：

    ``` js
    /**
     * Description of prop "aaa"
     * @default custom
     **/
    aaa: PropTypes.string,
    ```

7. 如果像添加属性枚举值的描述，可以采用下面方法


    ``` js
    /**
     * Description of prop "aaa"
     * @enumdesc left, right
     **/
    bbb: PropTypes.oneOf(['left', 'right']),
    ```

8. 可以通过书写 description tag 来为组件增加描述

    ``` js
    /**
     * Upload.ImageUpload
     * @description 继承 [Upload](http://fusion-demo.alibaba-inc.com/api/1.0/views/next?themeId=next&name=upload#upload-1) 的 API，除非特别说明
     */
    class ImageUpload extends Component {
      //...
    }
    ```
9. 以下的写法，可以获得 Base 组件中声明的 API 信息

    ``` js
    import Base from './base';

    export default class Menu extends Component {
        static propTypes = {
            ...Base.propTypes,
            /**
             * description
             */
            onSelect: PropTypes.func
        }
    }
    ```

---
_Source: https://npm.io/package/@alifd/api-extractor · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
