最近公司开发项目需要前后端分离,这样话就设计到后端接口设计。复杂功能需要提供各种各样的接口供前端调用,因此编写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文档啦

基于 Markdown 编写接口文档的更多相关文章

  1. Markdown编写接口文档模版

    接口名称 1) 请求地址 https://apis.cnblogs.com/user/info?a=xx&b=xx 2) 调用方式:HTTP GET 3) 接口描述: 接口描述详情 4) 请求 ...

  2. Markdown写接口文档,自动添加TOC

    上回说到,用Impress.js代替PPT来做项目展示.这回换Markdown来做接口文档好了.(不敢说代替Word,只能说个人感觉更为方便)当然,还要辅之以Git,来方便版本管理. Markdown ...

  3. 使用 Laravel-Swagger 编写接口文档(php)

    使用 Laravel-Swagger 编写接口文档 Table of Contents Swagger 文档管理 官方网站:https://swagger.io/ 快速编写你的 RESTFUL API ...

  4. 作为Java开发工程师,如何高效优雅地编写接口文档

    作为一名优秀的Java开发工程师,编写接口文档向来是一件很头疼的事情.本来就被bug纠缠的很累了,你还让我干这? 其实,你可以试试ApiPost. ApiPost的定位是Postman+Swagger ...

  5. 基于swagger进行接口文档的编写

    0. 前言 近期忙于和各个银行的代收接口联调,根据遇到的问题,对之前编写的接口进行了修改,需求收集和设计接口时想到了方方面面,生产环境下还是会遇到意想不到的问题,好在基本的执行逻辑已确定,因此只是对接 ...

  6. 几款常用的在线API管理工具(是时候抛弃office编写接口文档了)

    在项目开发过程中,总会涉及到接口文档的设计编写,之前使用的都是ms office工具,不够漂亮也不直观,变更频繁的话维护成本也更高,及时性也是大问题.基于这个背景,下面介绍几个常用的API管理工具,方 ...

  7. 使用 VS Code + Markdown 编写 PDF 文档

    背景介绍 作为一个技术人员,基本都需要编写技术相关文档,而且大部分技术人员都应该掌握 markdown 这个技能,使用 markdown 来编写并生成 PDF 文档将会是一个不错的体验,以下就介绍下如 ...

  8. 使用Spec Markdown 编写手册文档

    Spec Markdown 是一个基于markdown 的文档编写工具,安装简单,可以让我们编写出专业的文档 参考项目 https://github.com/rongfengliang/spec-md ...

  9. [API]使用Blueprint来高雅的编写接口文档 前后端api文档,移动端api文档

    网址:http://apiary.io/ 介绍:一款非常强大的前后端交互api设计编辑工具(编辑器采用Markdown类似的描述标记,非常高效),高颜值的api文档,还能生成多种语言的测试代码. 中文 ...

随机推荐

  1. video.js 一个页面同时播放多个视频

    $(data).each(function(i, item) { // innerHTML += '<li type-id="'+item.id+'">'+ // '& ...

  2. win10 64位IIS链接32位ACCESS数据库

    window10中IIS运行.asp文件链接数据库时出现错误,显示“An error occurred on the server when processing the URL. Please co ...

  3. 48.Odoo产品分析 (五) – 定制板块(3) – 修改文件和报告(1)

    查看Odoo产品分析系列--目录 不管ERP系统中的内置报表有多完善,大多数的公司仍然需要对文档和报表进行一些自定义的修改.  这一章节将介绍如何对报表的页眉和页脚做自定义修改:odoo框架如何组织报 ...

  4. 生鲜配送管理系统_升鲜宝V2.0 小标签打印功能说明_15382353715

    小标签打印说明 小标签打印可以打印本系统的订单商品数量,也可以把外部的订单商品导入本系统进行打印. 打印本系统中的订单商品操作说明 1.1    界面说明 1.2     查询条件 1.2.1     ...

  5. Python使用Plotly绘图工具,绘制直方图

    今天我们再来讲解一下Python使用Plotly绘图工具如何绘制直方图 使用plotly绘制直方图需要用到graph_objs包中的Histogram函数 我们将数据赋值给函数中的x变量,x = da ...

  6. Java中字符串相加和字符串常量相加区别

    有一道这样的程序: public class TestStringDemo { public static void main(String[] args) { String s1 = "P ...

  7. “等一下,我碰!”——常见的2D碰撞检测

    转自:https://aotu.io/notes/2017/02/16/2d-collision-detection/ 在 2D 环境下,常见的碰撞检测方法如下: 外接图形判别法 轴对称包围盒(Axi ...

  8. MyDAL - .UpdateAsync() 使用

    索引: 目录索引 一.API 列表 1.UpdateAsync() 用于 单表 更新操作 二.API 单表-便捷 方法 举例-01 var pk1 = Guid.Parse("8f2cbb6 ...

  9. github在README.md中插入图片

    例子 ![image](https://raw.githubusercontent.com/sunday123/Pendant/master/1.PNG)

  10. lua os.date函数定义和示例

    os.date函数定义 原型:os.date ([format [, time]]) 解释:返回一个按format格式化日期.时间的字串或表. lua源码中os.date的注释如下: --- --- ...