亲宝软件园·资讯

展开

【硬核教程】只需1秒—你也可以有自己的API文档

detectiveHLH 人气:3

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: 吹

加载全部内容

相关教程
猜你喜欢
用户评论