基于 Markdown 编写接口文档

2021-12-01 06:24:45

最近公司开发项目需要前后端分离，这样话就设计到后端接口设计。复杂功能需要提供各种各样的接口供前端调用，因此编写API文档非常有必要了

网上查了很多资料，发现基于Markdown编写文档是一种比较流行而且成熟的方案了，话不多说，我也搞一搞试试。

电脑操作系统：deepin深度 Linux64位，比较难用的一个系统，但是公司强制使用，没办法

1、这里我用到了gitbook，GitBook 是一个基于 Node.js 的命令行工具，支持 Markdown 和 AsciiDoc 两种语法格式，可以输出 HTML、PDF、eBook 等格式的电子书。关于更多介绍可以参考：http://www.chengweiyang.cn/gitbook/introduction/README.html 。安装gitbook可以直接使用命令： npm install gitbook-cli -g 来进行安装。当然前提是安装了nodejs ，因为我们前端项目用的vue，加载依赖也需要nodejs，所以我已经提前装好了直接使用。安装nodejs可以参考：https://www.cnblogs.com/liuqi/p/6483317.html（非常赞）

执行完上面命令以后，可能需要设置软连 nodejs中的gitbook ：ln -s /opt/nodejs/bin/gitbook /usr/local/bin/gitbook ，然后执行gitbook -V 来查看版本，首次会自动安装gitbook。

2、安装好gitbook以后，你就可以新建一个目录，mybook ，然后进去直选命令两个命令：gitbook init ， gitbook serve。 gitbook init命令是初始化你的书籍，会自动生成两个文件，SUMMARY.md可以理解为整个书籍的目录。如下图：

然后继续直行gitbook serve 就会根据SUMMARY.md来编译书籍如下：

然后就可以通过 http://localhost:4000/ 地址访问啦。

提示：我刚安装好gitbook以后是执行不到 “gitbook” 这个命令的，可以通过创建软链接解决，root权限下，执行： ln -s /opt/nodejs/bin/gitbook /usr/local/bin ，然后退出root就可以执行 gitbook命令啦，可以通过gitbook -V来查看版本

3、gitbook准备就绪，然后你还需要一个编辑工具，编辑工具应该有很多，我找到了一个是 Typora ，用了一下感觉还是比较好用，以后有机会再用其他的吧。 Typora安装可以参考官网，https://www.typora.io/#linux ，安装也非常简单。

执行以下命令：

# or run:

# sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys BA300B7755AFCFAE

wget -qO - https://typora.io/linux/public-key.asc | sudo apt-key add -

# add Typora's repository

sudo add-apt-repository 'deb https://typora.io/linux ./'

sudo apt-get update

# install typora

sudo apt-get install typora

需要注意的是 add-apt-repository 这个命令是需要安装一个python包的，直接执行：apt-get install python-software-properties 安装完成以后应该就可以执行了。如果还是不行，可以自行google或者百度一下

4、Typora 安装好以后，就可以用它打开文档进行编辑了，去mybook目录下，执行 typora SUMMARY.md 就可以进行编辑啦，然后下面就是SUMMARY的内容，使用 markdown语法进行编辑就可以了。

# Summary

* [前言](README.md)

* [一、登录模块](Chapter1/README.md)

    * [登录接口](Chapter1/登录接口.md)

    * [登录发送短信](Chapter1/登录发送短信.md)

    * [提交短信&支付密码登录](Chapter1/提交短信&支付密码登录.md)

使用typora打开以后，效果图如下：

5、大功告成，gitbook可以实时刷新，当你用编辑器修改内容以后，马上就可以在浏览器中看到效果。如果需要新增页面，就直接修改SUmmary.md，修改完成页面以后，执行 gitbook init就会自动创建。然后再用 typora打开编辑就行了。

后记：还可以使用gitbook功能生成pdf文档，但是需要提前安装 sudo apt-get install calibre 包，如果不安装执行命令会报 InstallRequiredError: "ebook-convert" is not installed. Install it from Calibre: https://calibre-ebook.com 错我。
在书籍目录下执行命令：gitbook pdf ，就可以生成pdf文档啦

码农公寓

相关文章