概要
肺炎横行，在家宅着的时间写了一个小服务，基于 Redis 键失效的时间点提醒服务，用来解决项目中遇到的部分轮询问题
之前写文档都是用Markdown来写，但是一直也没有重视格式及可读性，于是花点时间研究了一下网上用 Markdown 格式编写文档的经验，经过筛选和取舍，记录一下个人认为较好的接口文档的格式
碎碎念
我认为较好的文档应该有一下几个特点
- 纯文本，可版本管理，便于查看修改记录
- 易于编写，组内一系列文档不同人编写应该有相似风格
- 文档简洁，风格良好，可读性高
基于以上，我在编写文档的时候做了以下取舍
- 采用 Markdown 语法，没有使用 Office 系列
- 使用 Typora 编辑器，搭配 Vue (https://theme.typora.io/theme/Vue/) 主题，默认主题有些单薄
- 内容上，接口文档应该有接口修改记录，接口描述，补充说明等
示例图片
使用 Firefox 打开 PDF
火狐浏览器的字体会稍微加粗一点，看PDF的效果蛮不错的
接口地址使用统一格式进行描述
返回值特殊情况进行说明
文档中包含补充说明对约定俗成和状态码进行说明
示例下载
PDF下载：https://pan.yasking.org/demo/markdown-doc-demo.pdf
Markdown文件下载：https://pan.yasking.org/demo/markdown-doc-demo.md
之后编写接口文档，如果有更好的方案，风格，样式，我会在这里追加更新