使用 Markdown 编写接口文档

Published: 2020-02-01

Tags: markdown

本文总阅读量

概要

肺炎横行,在家宅着的时间写了一个小服务,基于 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

之后编写接口文档,如果有更好的方案,风格,样式,我会在这里追加更新