【硬核教程】只需1秒—你也可以有自己的API文档
Nothing is true. Everything is permitted.
写在前面
先聊聊 为什么 想到了要用Vuepress来代替原来写在Confluence上的文档。
大意是有个需要其他部门接入的项目,这个项目有个用md写的 接入文档 ,其他部门的人需要看着这个文档才知道怎么接以及哪些东西需要接。
但是有个问题是这个文档长的一匹,有多长呢?
而且这个md文件是放在confluence上的。
本身用confluence阅读md的体验就不好,这个文档能够让你的滚轮滚个足足十多秒,skr~。
你想要看的某个小章节就藏在这一大坨文字里。即使从最上面的导航锚点定位到了想要看的地方,但是你看着看着,滑着滑着就不知道自己在哪儿了。
然后找了半天,要么你运气好找到了。要么就只有回到最上面的导航,在一堆导航里再找一次。如果你运气究极不好,可能还要把上面的步骤重复几次,真的到了那个时候,你的心态可能就炸了。还接个毛的业务,心里只想找到写文档的人,然后一顿操作。
这就是为什么,我想换个方式来展示这个 接口文档 。
说到这个,又不得不吐槽。去网上找了很多vuepress的使用,总体下来两个字, 复杂 。再去看看vuepress的官方文档(虽然最后的解决方案都是在官方找到的),总结下来也是两个字, 懵逼 (因为我想找的那个地方藏得比较深)。
于是就有了写这一期 硬核教程 。
Don’t BB, 你这个项目启起来到底啥样?
我看的很多教程,都是在没有背景、没有代码、没有效果的情况就开始了。让本来希望通过这个教程入门的人懵上加懵(比如我)。
直接 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: 吹:ox::beer: details: 这是吹:ox::beer:的详情 - title: 继续吹:ox::beer: details: 这是继续吹:ox::beer:的详情 - title: 再继续吹:ox::beer: details: 这是再继续吹:ox::beer:的详情 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的张三', ] } ]
然后就可以在详情多看到一些页面了。
在vuepress中,如果路由以 /
结尾,那么就是指的这个目录下的README.md文件
还有一点很方便的是,单个文件里如果你有二级标题,vuepress会自动的生成该文件下的二级标题导航。点击相应的二级标题还可以直接跳转到对应的锚点,如下图。
如果你还需要更多功能
如果你作为一个后端开发, 要想展示你的文档,其实我认为完全够了。
不过你还需要更多功能的话,建议还是直接去 vuepress官网 查看对应的文档。
点个赞 ,
关个注 ,
分个享 ,
留个言
也可以微信搜索公众号【SH的全栈笔记】,当然也可以直接扫描二维码关注
拜了个拜