Monday, October 3, 2016

API 文件撰寫考慮的重點

公司在開會時,討論到我們該如何統一公司 API 文件的規範。本來大家都各說各話,主管則是表達:「請大家設法形成共識,不要讓我去推動一個 80% 的人都無法遵守的規範。」

終於,資深工程師M大大,發表了他對於 API 文件的先知卓見:

1 在我以前任職的公司,並沒有這種「先把程式寫完才寫 API 文件的這種開發方式。」一種可以做出穩定軟體產品的作法,是要先構思 API ,構思清楚之後才開始開發。 API 文件的重要性,可以類比資料庫的 schema 。

2 我個人比較重視下列三件事:
   (a) 編寫文件的表現自由度
   (b) 文件的格式必須是公開的格式,可以被改變的。因為外在的環境總是不停地在改變。
   (c) 是否可以快速地切換「檢視模式」和「編輯模式」

首先,apiary 這個平台,雖然有提供一些 sugar ,可以自動生成一些測試、說明,但是,它的平台功能並不是非常完整,同時也限制了編寫文件的自由度。如果需要撰寫的 API 是 stateful 的,是特別複雜的,其實用這種平台反而不會特別好用。這種平台只適合 API 的數目不多, API 相對單純的情況。於是,這個就導出了一個議題,是要選擇「半自動生成的 API 文件」還是選擇「純手刻但是 100% 自由的編寫方式」。如果考慮要做出高品質的文件,我還是傾向於後者。

關於文件格式的部分,我本來寫的文件一開始是用 mark down 寫在 gitbook 上,後來移到 trac 的 wiki 上。雖然 mark down 和 wiki 的語法不同,但是這些格式只要取代之後即可。所以使用公開的格式是很重要的。因為承載文件的平台很有可能會一直變換。然而,如果一開始是用 word 來寫,噢,那就糟了。

最後,像是 apiary 這個平台,它要快速切換「檢視模式」和「編輯模式」,並不是很順。然而,寫 API 文件如果要寫得清楚,就難免要用到比較進階的「格式化選項」。這時候就勢必要用肉眼來檢查,格式指令是否正確。所以能否快速切換,這個也是考量的重要條件。