【硬核教程】只需1秒—你也能够有本身的API文档

Nothing is true. Everything is permitted.

写在前面

先聊聊为何想到了要用Vuepress来代替原来写在Confluence上的文档。

大意是有个须要其余部门接入的项目，这个项目有个用md写的接入文档，其余部门的人须要看着这个文档才知道怎么接以及哪些东西须要接。

可是有个问题是这个文档长的一匹，有多长呢？

并且这个md文件是放在confluence上的。

自己用confluence阅读md的体验就很差，这个文档可以让你的滚轮滚个足足十多秒，skr~。

你想要看的某个小章节就藏在这一大坨文字里。即便从最上面的导航锚点定位到了想要看的地方，可是你看着看着，滑着滑着就不知道本身在哪儿了。

而后找了半天，要么你运气好找到了。要么就只有回到最上面的导航，在一堆导航里再找一次。若是你运气究极很差，可能还要把上面的步骤重复几回，真的到了那个时候，你的心态可能就炸了。还接个毛的业务，内心只想找到写文档的人，而后一顿操做。

这就是为何，我想换个方式来展现这个接口文档。

说到这个，又不得不吐槽。去网上找了不少vuepress的使用，整体下来两个字，复杂。再去看看vuepress的官方文档（虽然最后的解决方案都是在官方找到的），总结下来也是两个字，懵逼（由于我想找的那个地方藏得比较深）。

因而就有了写这一期硬核教程。

Don't BB, 你这个项目启起来到底啥样？

我看的不少教程，都是在没有背景、没有代码、没有效果的状况就开始了。让原本但愿经过这个教程入门的人懵上加懵（好比我）。

Github地址： -> 戳此 <-

*墙裂建议，先拉下来看看效果。*

直接npm install安装完依赖以后，直接npm start便可。在你本地的8080端口就会运行一个以下的界面。

并非自动打开浏览器，须要手动进入本地项目地址

而后点开始开发会进入到以下的详细界面。

左边就是咱们须要详细展现的文档，能够看到我简单的分了两类做为样例。

好了好了，效果看到了，Show me the code

首先，这个项目的目录长这样。

.
├── .vuepress
│   ├── config.js
│   ├── public
│   │   └── logo.jpg
│   └── router.js
├── LICENSE
├── README.md
├── groupA
│   ├── README.md
│   └── 类别A的李四.md
├── groupB
│   ├── README.md
│   └── 类别B的张三.md
├── package-lock.json
└── package.json

接下来就分别将一下首页和详情页是怎么来的，以及若是须要加一个页面（也就是路由）该怎么作。

首先是首页

项目的根目录下的README.md就是你刚刚看到的首页。里面的源码长这样，你能够对比首页来看。

---
home: true
heroImage: /logo.jpg
heroText: 你的标题
tagline: 你的副标题
lang: en-US
actionText: 开始开发 →
actionLink: /groupA/
features:
- title: 吹🐂🍺
  details: 这是吹🐂🍺的详情
- title: 继续吹🐂🍺
  details: 这是继续吹🐂🍺的详情
- title: 再继续吹🐂🍺
  details: 这是再继续吹🐂🍺的详情
footer: MIT Licensed | Copyright © 2019-present LunhaoHu
---

配成上面这样，你就能够看到刚刚那个首页。

没错，不用你去写任何的JavaScript和CSS，所有都是基于配置的。

顺嘴一提，只要你把图片放在了 .vuepress的public目录下，那么写图片src的时候能够直接 /你的图片名便可。

而后是详情页

能够看到，在首页的配置中，有一个actionLink，这个是指点了首页中的开始开发，须要跳转到的路由。这个就是咱们众多详情中的其中一个页面的路由。

你能够对比刚刚详情页的图片。咱们之因此可以看到左边的侧边栏，是由于在config.js里配置了sidebar这个属性。以下。

const router = require('./router');

module.exports = {
    smoothScroll: true,
    title: '须要你在config.js里单独配的标题',
    themeConfig: {
        sidebar: router.getSidebar()
    },
    plugins: ['vuepress-plugin-smooth-scroll'],
};

我这里只用了一个插件，可是我展现出了用插件的正确姿式，vuepress有不少插件，若是须要能够本身按需安装。

let data = [
    {
        'title': '类别A',
        'path': '/groupA/',
        'children': [
            '类别A的李四',
        ]
    },
    {
        'title': '类别B',
        'path': '/groupB/',
        'children': [
            '类别B的张三',
        ]
    }
];

/**
 * 生成sidebar数据
 *
 * @param data 上面定义的抽象侧边栏路由静态文件
 */
exports.getSidebar = () => {
    let sidebar = [];
    data.forEach((item) => {
        if (item.children.length === 0) {
            sidebar.push(item);
            return;
        }

        for (let i = 0; i < item.children.length; i++) {
            let childrenPath = item.children[i];
            item.children[i] = item.path + childrenPath;
        }
        sidebar.push(item);
    });
    return sidebar;
};

getSidebar这个函数，大意就是给全部的children加上了一个前缀path。由于vuepress自己须要你配置成这样。例如，若是你直接使用的话，路由就会变成这样。

注意，如下不是正确打开方式

[
  {
    title: '类别A',
    path: '/groupA/',
    children: [
      '/groupA/类别A的李四'
    ]
  },
  {
    title: '类别B',
    path: '/groupB/',
    children: [
      '/groupB/类别B的张三',
    ]
  }
]

在children中再加前缀，显得很没有必要。因此我简单的作了一层抽象。

那么若是你要加一个页面要怎么作呢？

举个例子，加入你要在项目目录groupA中新建一个叫类别A的王五.md的md文件，那么你只须要在对应的router中，找到groupA这个类别，而后在children数组中再加一个类别A的王五便可。以下。

正确打开方式

[
    {
        'title': '类别A',
        'path': '/groupA/',
        'children': [
            '类别A的李四',
            '类别A的王五'
        ]
    },
    {
        'title': '类别B',
        'path': '/groupB/',
        'children': [
            '类别B的张三',
        ]
    }
]

而后就能够在详情多看到一些页面了。

值得注意的是，groupA和groupB的目录下的README文件就是你点击类别A这个分组显示的默认页面。

在vuepress中，若是路由以/结尾，那么就是指的这个目录下的README.md文件

还有一点很方便的是，单个文件里若是你有二级标题，vuepress会自动的生成该文件下的二级标题导航。点击相应的二级标题还能够直接跳转到对应的锚点，以下图。

若是你还须要更多功能

若是你做为一个后端开发， 要想展现你的文档，其实我认为彻底够了。

不过你还须要更多功能的话，建议仍是直接去vuepress官网查看对应的文档。

若是你以为这篇文章对你有帮助，还麻烦 点个赞， 关个注， 分个享， 留个言

也能够微信搜索公众号【SH的全栈笔记】，固然也能够直接扫描二维码关注

拜了个拜