API文件除了使用word, google doc撰寫之外,其實可以有更多選擇。
現在有許多開源社群1能夠自動產生API文件
API Blueprint是一種開源的API語言
主要使用markdown語法來描述你的API
目前有許多工具可以直接從source code parse出API描述檔案
或者你也可以使用editor直接撰寫API描述檔案
之後再把API描述檔案render成html靜態文件
除了有美美的文件以及能夠解決文件與程式碼不同步的問題之外
還有許多人做出實用的小工具
例如可以將API描述檔案轉承對應的source code(這是一個遠大的理想,目前實用性也許還不高…)
或者將API描述檔案轉成Postman的script
也有套件可以直接根據API描述檔案一鍵建立mock server
API bluerprint自成一種開源社群
你可以貢獻自己寫的任何工具!