前言

傳統的做法是用office寫接口文檔,這種方式的缺點很多:

格式混亂

事實上,所有的傳統富文本文檔都存在這個問題,富文本的跨平台兼容性很差,很容易造成格式錯亂。

版本管理困難

依賴文件系統管理文檔是很落後的做法,很難保證手頭的文檔是最新的版本。

兼容性差

不是所有人都用windows。

低效

對效率的負面影響很大程度上已經包含在前面幾項里。此外,編輯工具的臃腫、編輯內容的同時還要調整樣式、缺少全文檢索等,也是導致效率下降的原因。

理想情況

理想的接口文檔應該有以下特徵:

方便創作

文檔編輯最重要的是文檔的內容,而不是編輯操作本身。所以編寫文檔的過程應該是簡單快捷的,而且最好不需要額外的學習成本。

排版簡潔規範

技術文檔的排版,簡潔規範是最重要的,花哨的排版會降低效率。

方便查閱

應該有目錄或者大綱視圖,並且可以方便地全文檢索。

在線協作

傳統的離線文檔不方便協作。

多端兼容

允許在大多數常見平台編輯和使用文檔。

版本管理

可以查看什麼人在什麼時間改了哪些內容。

交互式文檔

所見即所得。可以修改參數、發送請求並查看接口返回值。

可訂閱

可以給接口打標籤。用戶可以訂閱任意標籤下的接口變更,也可以針對接口訂閱。

自動生成

如果代碼的可讀性足夠好,何必浪費時間寫文檔?或者至少可以自動生成。

當前實踐

理想很豐滿,但是目前還沒有能滿足以上所有需求的解決方案。權衡之下,markdown和wiki是目前比較合適的方案。

markdown

用markdown寫文檔有以下特點:

  • 適合單文檔形式
  • 主流git托管平台都支持
  • 適合個人創作
  • 適合小型項目、需要移交開發成果的項目

下面是用markdown寫的接口文檔的例子:

主流markdown編輯器在轉換過程中會為標題添加錨點,利用這個特性可以實現從接口列表跳轉到接口詳情。

最佳工具

Cmd Markdown

  • 美觀
  • 跨平台
  • 編輯操作支持Vim模式

wiki

用wiki寫文檔有這些特點:

  • 方便多層級文檔
  • 需要自己搭建平台
  • 適合團隊創作
  • 適合長期、大型項目

最佳工具

dokuwiki

  • 剛剛好

結論

綜上,小型的、托管在主流git平台的項目適合用markdown,公司級項目用wiki更好。但這還達不到理想的標準,需要繼續探索更好的解決方案。