@esydoc/resolver-doc2

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

安装

npm i @esydoc/resolver-doc2 -D

使用

• 在 esydoc.config.js 文件中的 resolves 字段添加@esydoc/resolver-doc2 对应的基础配置

// for example in esydoc.config.js
{
   apiConfigDefaultOutputPath: 'src/edoc-api-config',
  resolves: {
    '@esydoc/resolver-doc2': {
      includes: [],
      output: {
        template: 'hyext-docs',       // 固定使用这个模版
        dist: './docs',               // 构建产物地址
      },
      pathPrefix: 'hyExt',            // 接口前缀
      innerModules: ['advance'],      // 内部模块
      expendDocPath: './expend-docs', // 接口扩展描述目录
    }
  }
}

• 修改 src/edoc-api-config 下每个接口配置信息
• 运行行脚本：# esydoc --config esydoc-doc.config.js

基础配置

• pathPrefix:string 接口调用前缀，默认：hyExt；
• innerModules: string[] 内部模块，不对外；
• expendDocPath: string 接口扩展描述目录;
• extraData: Object 额外文渲染数据，可在模版渲染时引用；
• template: TemplateOptions 扩展模板配置；
• plugins: Array<any> 自定义插件，自定义扩展用；

type DocOptions = {
  /**
   * 调用前缀
   */
  pathPrefix: string
  /**
   * 内部模块
   */
  innerModules?: string[]
  /**
   * 接口扩展描述目录
   */
  expendDocPath?: string
  /**
   * 扩展模板配置
   */
  template?: TemplateOptions
  /**
   * 自定义插件
   */
  plugins?: Array<any>
}

expendDocPath 接口扩展描述目录

• 存放接口扩展描述的目录位置；
• 目录结构：

└── expend-docs              // 扩展文件存放目录
  ├── outer                  // 外部文档扩展
  │ ├── hyExt.env.getExtInfo // 要扩展的接口
  │ │ ├── extraPrepare.md    // 接口文档准备信息扩展，接口描述之后；
  │ │ ├── extraSign.md       // 接口文档调用签名扩展，接口签名之后；
  │ │ ├── extraExamples.md   // 接口文档调用示例扩展，调用示例之后；
  │ │ └── extraLinks.md      // 接口文档相关链接扩展，文档最底部；
  │ └── hyExt.xx.xx          // 更多扩展接口
  │
  └── inner                   // 内部文档扩展

• 使用示例：

template 扩展模板配置

• 关于 Handlebars
• partial: string[] handlebars partial 模版文件路径
• helper: string[] handlebars helper 数据处理文件路径
• extraAPIPages: PageTemplate[] 额外接口页面模版，每个 API 都会渲染（仅对外）
• extraOncePages: PageTemplate[] 额外单页面模版，仅渲染一次（仅对外）

说明

/** 模版配置 */
type TemplateOptions = {
  /**
   * handlebars partial 模版文件路径
   */
  partial?: string[]
  /**
   * handlebars helper 数据处理文件路径
   */
  helper?: string[]
  /**
   * 额外API页面模版，每个API都会渲染
   */
  extraAPIPages?: PageTemplate[]
  /**
   * 额外单页面模版，仅渲染一次
   */
  extraOncePages?: PageTemplate[]
}

/** 页面模版信息 */
type PageTemplate = {
  /**
   * 是否是仅外放页面模板
   */
  publish?: boolean
  /**
   * 文档生成路径
   */
  filePath: string | ((data: any) => string)
  /**
   * 文档模版，handlebars 格式模版
   */
  template: string
}

示例

// for example in esydoc.config.js
{
  resolves: {
    '@esydoc/resolver-doc2': {
      // ....
      template: {
        /** 模板路径 */
        partial: [path.join(__dirname, 'partials/**.hbs')],
        /** helper 路径 */
        helper: [path.join(__dirname, 'helpers/**.js')],
        /** 额外模版 */
        extraOncePages: [
          {
            publish: true,
            filePath: path.join('sdk', 'index.md'),
            template: `{{>home-header}}\n{{>home-list}}`,
          },
        ]
      }
    }
  }
}

plugins 扩展插件

• 自定义扩展插件，可自定义扩展编译配置

示例

class HYExtDoc2Plugin {
  constructor(options) {
    this.options = options
  }

  apply(docResolver) {
    // 渲染前，修改配置
    docResolver.hooks.renderBefore.tap('HYExtDoc2Plugin', (dataByHandlebar) => {
      Object.assign(dataByHandlebar.payload, this.options)
      return dataByHandlebar
    })
  }
}

接口配置

• 配置位置 edoc-api-config/${pathPrefix}.xx.xx.js
• compatibility: Compatibility 接口兼容性；
• type: string 接口类型，对外文档分类；
• onlyInner: boolean 仅内部模块标识，接口不对外；
• description: string 接口说明，会覆盖 jsDoc 里的 description；
• summary: string 接口简述，会覆盖 jsDoc 里的 summary；
• since: string 支持版本，会覆盖 jsDoc 里的 since；
• example: string 调用示例，覆盖默认生成的调用示例；

/**
 * 接口配置信息
 */
type DocConfig = {
  /**
   * 接口兼容性
   */
  compatibility?: Compatibility
  /**
   * 接口类型，对外文档分类；
   */
  type?: string
  /**
   * 仅内部模块标识
   */
  onlyInner?: boolean
  /**
   * 调用示例，可覆盖默认生成的调用示例
   */
  example?: string
  /**
   * 接口说明，可覆盖默认的接口说明，内容尽量精简
   */
  description?: string
  /**
   * 接口简述，可覆盖默认的接口描述
   * 描述示例
   *    缩进示例
   */
  summary?: string
  /**
   * 版本，最低支持版本
   */
  since?: string
}

compatibility 接口兼容性

• 标记当前接口在各个端支持情况；
• 不配置的端表示不支持；

说明

/**
 * 接口兼容性
 */
type Compatibility = {
  /**
   * WEB主站 兼容状态
   */
  web?: Status
  /**
   * 观众APP【iOS】兼容状态/版本
   */
  app_ios?: Status | string
  /**
   * 观众APP【安卓】兼容状态/版本
   */
  app_adr?: Status | string
  /**
   * 助手APP【观众端APP【iOS】】兼容状态/版本
   */
  zs_ios?: Status | string
  /**
   * 助手APP【安卓】兼容状态/版本
   */
  zs_adr?: Status | string
  /**
   * PC观众端 兼容状态/版本
   */
  pc_viewer?: Status | string
  /**
   * PC主播端 兼容状态/版本
   */
  pc_streamer?: Status | string
}

/** 兼容状态 */
enum Status {
  /** 未验证 */
  UNVERIFIED = 0,
  /** 已通过 */
  PASS = 1,
  /** 不通过 */
  UNPASS = 2,
  /** 未实现 */
  UNIMPLEMENT = 3,
  /** 不支持 */
  UNSUPPORT = 4,
}

示例

• edoc-api-config/${pathPrefix}.xx.xx.js 配置文件

{
  doc: {
    compatibility: {
      web: 1,            // web端都支持 // 0: 未验证; 1: 已通过; 2: 不通过; 3: 未实现; 4: 不支持;
      app_ios: "10.1.1", // 观众APP【iOS】从 10.1.1 开始支持
      app_adr: "10.1.1", // 观众APP【安卓】从 10.1.1 开始支持
      zs_ios: 3,         // 助手APP【iOS】暂未实现
      zs_adr: 3,         // 助手APP【安卓】暂未实现
      pc_viewer: 3,      // PC观众端 暂未实现
      pc_streamer: 3,    // PC主播端 暂未实现
    },
  },
}