vuepress-apidoc 简介

一个能解析 jsdoc 注释和 vue 文件并生成 api 文档的 vuepress 插件

功能

• 根据 js、vue 文件 jsdoc 注释输出 markdown 文件；
• 展示 vue 组件，配合使用我的另一个 vuepress 插件，vuepress-plugin-vue-compdemo，识别自定义 md 容器，基本可以和 element-ui 一样的展示效果，具体参考该插件说明文档
• 可自定义分类输出侧边文档导航栏；
• 兼容 vuepress 目前所有版本 v0.x、v1.x 和 v2.x；

生成 jsdoc 注释

• 一般 vscode 有很多这类的插件：一般我是用的是 Document This

起步

# 安装
npm i -D vuepress-apidoc

# 生成api文档
vuepress-apidoc -c 配置文件路径

# 例如，自行在本地创建config文件
vuepress-apidoc -c ./config/config.js

# 或
vuepress-apidoc -c ./config/config.json

命令行参数

• -c：配置文件配置文件路径（必须）
• -v：查看版本号

产物

• md 文件（一般将其输出路径dist设置到 vuepress 的 docs 目录即可）
• sidebar 的 config.js 文件

使用 sidebar 的 config.js 文件

• 一般是在 vuepress 项目的配置文件中引入
• 例如：vuepress 的 v2.x 版本的配置文件在.../docs/.vuepress/config.js 中引入

// docs/.vuepress/config.js
// 引入导出的sidebar配置config.js
const { getApiSidebarList } = require('../api/config')
let sidebarList = {
  // 这里可以写你其他的侧边栏导航
  // 例如
  // v1.x、v0.x
  // '/other/': [
  // {
  //   title: 'other',
  //   collapsable: false, // 可选的, 默认值是 true,
  //   children: ['/other/other.md']
  // }
  // v2.x
  // '/other/': [
  //   {
  //     text: 'other',
  //     children: [
  //       '/other/other.md'
  //     ]
  //   }
  // ]
}

// 将getApiSidebarList()返回的对象，覆盖到sidebarList
sidebarList = Object.assign({}, sidebarList, getApiSidebarList())

// vuepress配置
module.exports = {
  themeConfig: {
    sidebar: sidebarList
  }
}

config 配置文件

• 接受两种文件格式：.js 或者.json

• src（array）：js 文件目录或文件路径

• rotuerName（string）：输出 vuepress 导航路由名，默认：'api'

• dist（string）：markdown 文件和 sidebar 配置文件输出目录路径，默认：'../docs'

• readme（object）：rotuerName路由下的首页 README.md 文件配置，若不设置，则默认输出所有 api 的 md 文件列表并写出新的 README.md

  • path（string）：输入的 README.md 文件路径，默认：空
  • outputName（string）：输出名称，默认：README.md
  • isOutputApiList（boolean）：是否在 README.md 最后追加所有 api 的 md 文件列表数据，默认：true

• sidebarTree（array）：自定义 vuepress 的 sidebar 分类，默认：归类到 API 栏下

  • title（string）: 分类名称
  • include（array）: 该分类包含的源文件匹配，多个规则只要符合一个规则就会添加
  • exclude（array）: 该分类忽略的源文件匹配，多个规则只要符合一个规则就会忽略

• info（boolean）：是否输出详情日志，默认：true

• include（array）：包含的源文件匹配，多个规则只要符合一个规则就会添加

• exclude（array）：忽略的源文件匹配，多个规则只要符合一个规则就会忽略

• vuepressVersion（number）：vuepress 的版本，例如 v1.x，则vuepressVersion:1，默认：2

• defaultSiebarName：默认的侧边栏分类名称，默认：'API'

• jsdoc（object）：jsdoc 的配置

  • configure（string）： getJsdocData 的 configure 配置项，既是 jsdoc 的配置文件路径

• vueDoc（object）：vue 文件文档配置

  • autoOutput（object）：vue 文件输出的 md 文档配置，默认都为 true，如果不需要则设置对应的为 false 即可
  • title（boolean）: 默认：true，是否输出顶部的 title
  • props（boolean）: 默认：true，是否输出 props
  • slot（boolean）: 默认：true，是否输出 slot
  • method（boolean）: 默认：true，是否输出 method
  • event（boolean）: 默认：true，是否输出 event

注意

• 该插件是根据配置文件所在目录作为源的根目录
• 例如配置文件路径在：E:\code\vuepress-apidoc\config\config.js
• 那么相对路径就是根据 E:\code\vuepress-apidoc\config，作相对的
• 在 config.js 配置项中写，"../src"，那么他的路径就是，E:\code\vuepress-apidoc\src
• 也可以在 config.js 配置 info 属性为 true，查看路径是否正确

文件匹配写法

• 参考：micromatch 的 contains 方法

config.js

const config = {
  src: ['../src'],
  rotuerName: 'api',
  dist: '../docs',
  defaultSiebarName: 'API',
  readme: {
    path: '../README.md',
    outputName: 'README.md',
    isOutputApiList: false
  },
  sidebarTree: [
    {
      title: '工具类',
      include: ['utils/**'],
      exclude: []
    }
  ],
  info: false,
  include: ['*.js'],
  exclude: ['node_modules'],
  vuepressVersion: 2,
  // jsdoc: {
  //   configure: ''
  // },
  // vue doc文档配置
  vueDoc: {
    // 输出配置，是否需要自动检测文件输出对应的 event、props、slot、method，默认都为true，如果不需要则设置对应的为false即可
    autoOutput: {
      title: true,
      // 是否输出props
      props: true,
      slot: true,
      method: true,
      event: true
    }
  }
}

module.exports = config

js 文件的 jsdoc

• 写法可以参考jsdoc

  /**
   * 订阅事件
   * @param {*} type 事件名
   * @param {*} scope 作用域
   * @param {*} callback 回调
   * @param {*} [params=[]] 回调参数
   * @memberof EventManager
   */
  on(type, scope, callback, params = []) {
    // 订阅的放到数组记录
    const listenerParams = { callback: callback, scope: scope, params: params, isOnce: false }
    this.addListener(type, listenerParams)
  }

vue 文件的 jsdoc

• 写法可以参考 vue-docgen-api、jsdoc

<template>
  <div class="Button">
    <button class="button" @click.prevent="onClick" :style="{ color: color, fontSize: fontSize }">
      <!-- @slot 这里是slot的jsdoc
                @binding {object}  text text of the menu item
      -->
      <slot name="test" :text="fontSize"> </slot>

      <button @click="click">点击</button>
    </button>
  </div>
</template>

<script>
  /**
   * 这里是组件的描述
   */
  export default {
    name: 'Button',
    props: {
      /**
       * The color for the button.
       */
      color: {
        type: String,
        default: '#333'
      },
      /**
       * The size of the button 其他的东西ddd
       * @values small, normal, large,ls
       *
       */
      size: {
        type: String,
        default: 'normal'
      },
      /**
       * Gets called when the user clicks on the button
       * @ignore
       */
      onClick: {
        type: Function,
        default: (event) => {
          console.log('You have clicked me!', event.target)
        }
      }
    },
    computed: {
      fontSize() {
        let size
        switch (this.size) {
          case 'small':
            size = '10px'
            break
          case 'normal':
            size = '14px'
            break
          case 'large':
            size = '18px'
            break
        }
        return size
      }
    },
    methods: {
      /**
       * Sets the order2222
       * @public
       * @version 1.0.5
       * @since Version 1.0.1
       */
      click() {
        /**
         * 这里是events的jsdoc
         * @event click
         * @property {number} newVal new value set
         * @property {number} oldVal new value set
         * @params  {number} newVal
         */
        this.$emit('click', newVal, oldVal)
      }
    }
  }
</script>

<style scope>
  .checks {
    background-image: linear-gradient(45deg, #f5f5f5 25%, transparent 25%), linear-gradient(-45deg, #f5f5f5 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #f5f5f5 75%), linear-gradient(-45deg, transparent 75%, #f5f5f5 75%);
    background-size: 16px 16px;
    background-position: 0 0, 0 8px, 8px -8px, -8px 0px;
  }
</style>

<!-- 直接引入md文件 -->
<docs>
  <demo>./Button.md</demo>
</docs>

如何在 vue 文件中直接引入 markdown 文件

• 插件会直接读取<demo>...</demo> 中间的路径文件内容，并输出到最后的 md 文件中
• 如果有需要可以输入多个 demo，但是一般一个就够了
• md 文件中，可以是任何 md 内容或是组件的演示文档vuepress-plugin-vue-compdemo

<!-- 像这样就可以了-->
<docs>
  <demo> 文件路径1 </demo>
  <demo> 文件路径2 </demo>
</docs>

参考

• micromatch
• vuepress
• commander
• jsdoc-to-markdown
• vue-docgen-api
• vuepress-jsdoc
• vuepress-plugin-vue-compdemo