@esydoc/resolver-doc

一个解析 Api 源码生成文档的解析器

Installation

npm i @esydoc/resolver-qa -D

Usage

在 esydoc.config.js文件中的resolves字段添加@esydoc/resolver-doc对应的配置就 ok 拉。

// for example in esydoc.config.js
{
  resolves: {
    '@esydoc/resolver-doc': {
      pathPrefix: 'global.hyExt',
      output: {
        template: "doc-website",
        dist: path.join(__dirname, "doc-website")
      }
    },
  }
}

Esydoc Extra Config

pathPrefix

调用路径前缀

hostContext

无。

API 配置文件对应配置

所有resolver-doc的配置都在命名空间doc内。

// api config file
{
  doc: {
    // resolver-doc config
  }
}

在esydoc整套体系来说，API的配置可分两种，第一种是扫描代码自动生成的，另外一种是手动填写。

自动生成部分

• example:string - resolver-doc会自动生成 demo 的代码，非常便利，生成的调用数据取得都是数据类型的默认值, 所以有些时候需要我们补上定制化的调用参数。

手动填写部分

• explanation?:string[] - resolver-doc会自动添加接口描述和版本号，所以这个字段是为了文档说明的填写补充。
• compatibility:Compatibility[] - 接口兼容性的描述配置。
• qa: QA[] - 接口 QA 的描述配置。

compatibility 和 qa的配置在resolver-doc内部有默认值，会帮助我们减少配置量。

Compatibility

兼容性配置的数据结构和默认值如下：

enum Status {
  pending, // 从0开始
  success,
  fail,
  noImplement,
  uninvolved
}

type Compatibility = {
  version: string
  web: Status.uninvolved
  app_ios: Status.uninvolved
  app_android: Status.uninvolved
  zs_ios: Status.uninvolved
  zs_android: Status.uninvolved
  pc_viewer: Status.uninvolved
  pc_streamer: Status.uninvolved
}

type CompatibilityList = Compatibility[]

QA

QA 配置的数据结构和默认值如下：

enum Status {
  pending, // 从0开始
  success,
  fail,
  noImplement,
  uninvolved
}

type QA = {
  platformName: string // web | app_ios | ..., 跟Compatibility内的平台有关字段保持一致
  platform: string
  auth: Status.success
  pass: Status.success
  reason: Status.pending
  frequency: Status.pending
}

type QAList = QA[]

DEMO

以advance.showLogin为例子:

接口配置：

{
  demo: {
    compatibility: [
      {
        version: '1.5.0',
        web: 1,
        app_ios: '7.13.353.15465',
        app_android: '7.13.6-34249',
        pc_viewer: '5.4.1.0',
        zs_ios: 4,
        zs_android: 4,
        pc_streamer: 4
      }
    ],
    qa: [
      {
        platform: 'pc_viewer',
        auth: 0,
      }
    ],
  }
}

生成结果：

advance.showLogin.md