编写接口文档的最佳实践

前言

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

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

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

不是所有人都用windows。

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

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

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

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

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

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

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

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

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

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

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

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

用markdown写文档有以下特点：

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

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

用wiki写文档有这些特点：

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