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
随机推荐
- NSURLSession -- 备忘
NSURLSession NSURLSession是iOS7出的API,在它之前常用的原生网络库是NSURLConnection,但是因为Connection的使用起来不是很方便 所以我们一直倾向于A ...
- ARC - MRC
1. 选择工程 ---> build phases --> .m中添加 -fno-objc-arc
- Servlet处理Cookie
1.CGI:进程,servlet:线程 2.HttpServletResponse下的方法就没有get开头的,(PrintWriter)getWriter在ServletResponse下. 3.st ...
- Warm up 2
hdu4619:http://acm.hdu.edu.cn/showproblem.php?pid=4619 题意:题目大意:给你两种纸牌 ,一种水平放置共有n张 ,一种竖直放置共有m张.水平放置的纸 ...
- 搭建DirectUi开发平台
DirectUi的效果可以使用GDI.GDI+.DirectX.OpenGL实现,常用的有GDI和GDI+,后两种有杀鸡用牛刀的感觉.在网络上能找到此方面的教材 现在的软件越来越多的有很炫目的界面,看 ...
- PL/SQL 程序块
DECLARE BARCODE VARCHAR(50); BEGIN BARCODE := 'A'; IF BARCODE<>'A' then SELECT 1 FROM sam_user ...
- java 中的访问修饰符
一. public:所有类都可以访问 protected:所有子类和同包下的类都可以访问 缺省:同包类都可以访问 private:类本身才可以访问 注意点:protected修饰类属性时,例如 pac ...
- 【HDOJ】1754 I Hate It
线段树. #include <iostream> #include <cstdio> #include <cstring> using namespace std; ...
- Light OJ 1050 - Marbles(概率DP)
题目大意: 一个包裹里有蓝色和红色的弹珠,在这个包裹里有奇数个弹珠,你先走, 你先从背包里随机的拿走一个弹珠,拿走每个弹珠的可能性是一样的.然后Jim从背包里拿走一个蓝色的弹珠,如果没有蓝色的弹珠让J ...
- LoadRunner监控Windows和Linux常见问题
LoadRunner 加载监听服务器的步骤如下: 1.在 LoadRunner Controller 下,将工作面板切换到 Run状态,Available Graphs 栏 ,System Resou ...