【硬核教程】只需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: 吹