前言

传统的做法是用office写接口文档,这种方式的缺点很多:

格式混乱

事实上,所有的传统富文本文档都存在这个问题,富文本的跨平台兼容性很差,很容易造成格式错乱。

版本管理困难

依赖文件系统管理文档是很落后的做法,很难保证手头的文档是最新的版本。

兼容性差

不是所有人都用windows。

低效

对效率的负面影响很大程度上已经包含在前面几项里。此外,编辑工具的臃肿、编辑内容的同时还要调整样式、缺少全文检索等,也是导致效率下降的原因。

理想情况

理想的接口文档应该有以下特征:

方便创作

文档编辑最重要的是文档的内容,而不是编辑操作本身。所以编写文档的过程应该是简单快捷的,而且最好不需要额外的学习成本。

排版简洁规范

技术文档的排版,简洁规范是最重要的,花哨的排版会降低效率。

方便查阅

应该有目录或者大纲视图,并且可以方便地全文检索。

在线协作

传统的离线文档不方便协作。

多端兼容

允许在大多数常见平台编辑和使用文档。

版本管理

可以查看什么人在什么时间改了哪些内容。

交互式文档

所见即所得。可以修改参数、发送请求并查看接口返回值。

可订阅

可以给接口打标签。用户可以订阅任意标签下的接口变更,也可以针对接口订阅。

自动生成

如果代码的可读性足够好,何必浪费时间写文档?或者至少可以自动生成。

当前实践

理想很丰满,但是目前还没有能满足以上所有需求的解决方案。权衡之下,markdown和wiki是目前比较合适的方案。

markdown

用markdown写文档有以下特点:

  • 适合单文档形式
  • 主流git托管平台都支持
  • 适合个人创作
  • 适合小型项目、需要移交开发成果的项目

下面是用markdown写的接口文档的例子:

主流markdown编辑器在转换过程中会为标题添加锚点,利用这个特性可以实现从接口列表跳转到接口详情。

最佳工具

Cmd Markdown

  • 美观
  • 跨平台
  • 编辑操作支持Vim模式

wiki

用wiki写文档有这些特点:

  • 方便多层级文档
  • 需要自己搭建平台
  • 适合团队创作
  • 适合长期、大型项目

最佳工具

dokuwiki

  • 刚刚好

结论

综上,小型的、托管在主流git平台的项目适合用markdown,公司级项目用wiki更好。但这还达不到理想的标准,需要继续探索更好的解决方案。