Markdown写接口文档,自动添加TOC
上回说到,用Impress.js代替PPT来做项目展示。这回换Markdown来做接口文档好了。(不敢说代替Word,只能说个人感觉更为方便)当然,还要辅之以Git,来方便版本管理。
Markdown基本语法也没啥好说的,随便百度一下几分钟看懂基本的,20%的知识完成80%的任务嘛,够了。
关键在于,我有些特殊需求,以方便将Markdown作为接口文档查看。什么需求呢?
目录。这是重中之重。没有方便的TOC的话,文档长了,查看起来真是费劲。我理想中的目录是这样的:
根据H1(# )、H2(## )号标题,自动生成索引,而不是网上其它人的什么标题都生成索引,弄一堆子乱七八糟的完全没有接口文档的感觉了。
这个目录一定得是浮动在侧边栏的,不能说要查某个接口还得先回到页首去。
这个目录还应该是自动折叠的,当我不需要它时它得到一侧缩着,不能碍事。
表格样式,一定得是易读的,字体不能小,分界要明显,每行颜色要深浅交错开,表头颜色要更深。
读取要方便,不能要求大家都装一个Markdown阅读器,不然又成Word了。我要求能直接从浏览器打开阅读。但是也不能说每次都上传到Github之类的地方去看,麻烦,而且Github也不支持自定义样式。最重要的是,我并没有Github上的私有仓库。
Ok,就这些需求。个人感觉要求不高吧?呵呵,找了半天还真没找到。于是乎,自己写了一个咯:https://github.com/zhengxiaoyao0716/MarkedWithToc。
简单来说,就是一张网页。把写好的.md文件拖拽上去,然后按照以上需求生成html预览自动生成目录、黑白两种为接口文档优化过的主题,一键保存到本地。配合git做版本管理,应该会方便很多。
就这样,本次不是教程,不是学习笔记,只是一个建议和推广,给所有追求变化爱折腾的程序猿。懒得进GitHub的,直接打开这个链接即可使用:http://temp.zheng0716.com/MarkedWithToc/。注意,第一个一级标题会被无视,因为要作为文档标题嘛。
Markdown写接口文档,自动添加TOC的更多相关文章
- 「快学springboot」16.让swagger帮忙写接口文档
swagger简介 官方的介绍 THE WORLD'S MOST POPULAR API TOOLING Swagger is the world's largest framework of API ...
- django接口文档自动生成
django-rest_framework接口文档自动生成 只针对用到序列化和返序列化 一般还是用第三方yipi 一.安装依赖 pip3 install coreapi 二.设置 setting.py ...
- 如何让接口文档自动生成,SpringBoot中Swagger的使用
目录 一.在SpringBoot项目中配置Swagger2 1.pom.xml中对Swagger2的依赖 2.编写配置类启用Swagger 3.配置实体类的文档 4.配置接口的文档 5.访问文档 二. ...
- 基于 Markdown 编写接口文档
最近公司开发项目需要前后端分离,这样话就设计到后端接口设计.复杂功能需要提供各种各样的接口供前端调用,因此编写API文档非常有必要了 网上查了很多资料,发现基于Markdown编写文档是一种比较流行而 ...
- 给.Net Core添加Swagger实现接口文档自动生成
1.添加Nuget相关引用 Swashbuckle.AspNetCore
- 与你相遇好幸运,aglio写接口文档
npm install -g aglio npm i aglio-theme-minimal aglio --theme-full-width -t minimal -i ./src/index.md ...
- markdown格式接口文档模板
源文件 https://files.cnblogs.com/files/bincoding/%E6%8E%A5%E5%8F%A3%E6%96%87%E6%A1%A3.zip 目录 测试接口 查询指定项 ...
- Markdown编写接口文档模版
接口名称 1) 请求地址 https://apis.cnblogs.com/user/info?a=xx&b=xx 2) 调用方式:HTTP GET 3) 接口描述: 接口描述详情 4) 请求 ...
- djangorestframework接口文档自动生成
参考: https://blog.csdn.net/ros_donggua/article/details/81007814 pip install coreapi
随机推荐
- winfrom获得鼠标的坐标
Point mouse = this.PointToScreen(Control.MousePosition);label1.Text = mouse.X.ToString() + ":&q ...
- PAT (Basic Level) 1004. 成绩排名 (20)
读入n名学生的姓名.学号.成绩,分别输出成绩最高和成绩最低学生的姓名和学号. 输入格式:每个测试输入包含1个测试用例,格式为 第1行:正整数n 第2行:第1个学生的姓名 学号 成绩 第3行:第2个学生 ...
- iconv
iconv -f 源字符集 -t 目标字符集 文件名 iconv -f UTF-8 -t GBK success.msg [root@perass ~]# cat success.msg | t ...
- codeforce ---A. Milking cows
A. Milking cows time limit per test 1 second memory limit per test 256 megabytes input standard inpu ...
- Hibernate(二)Hibernate 实例
上篇Hibernate(一)JDBC简介,我们主要对JDBC进行了简单介绍和使用说明,这次我们做一个Hibernate简单实例,通过这个实例对比Hibernate和JDBC,了解Hibernate的优 ...
- mac上的键盘生活——快捷键列表
主界面 command + tab 切换程序 command + ` 在程序内切换界面 command + w 关闭界面 command + q 关闭程序 文本编辑 Com ...
- PHP中Content-type的MIME类型大全说明
<?php $mimetypes = array( 'ez' => 'application/andrew-inset', 'hqx' => 'application ...
- effective C++ 读后笔记
首先不得不说侯捷翻译的书大部分我都很喜欢,因为侯捷本身是一名出色的C++技术专家.这本书讲的是C++如何高效的运行,我想要成为一名卓越的开发人员,代码的高效性是必不可少的.很多人的代码质量很差,即使能 ...
- 与IO相关的等待事件troubleshooting-系列5
'db file scattered read' 这是另一种常见的等待事件.他产生于Oracle从磁盘读取多个块到Buffer Cache中非连续(" scattered&q ...
- windows Nginx基本使用方法
相信很多人都听过nginx,这个小巧的东西慢慢地在吞食apache和IIS的份额.那究竟它有什么作用呢?可能很多人未必了解. 说到反向代理,可能很多人都听说,但具体什么是反向代理,很多人估计就不清楚了 ...