終於不用再苦逼地寫文檔了！教你如何產生可調試的API文檔

本文寫的是什麼？

平時總是要寫文件。不寫，程式碼無法維護，所以不得不寫。但寫文件費時費力，更可怕的是寫完了讀起來還很費勁，束之高閣，總覺得時間浪費掉了，真是苦不堪言。

一直深受「寫文件」的折磨，偶然看到一篇神文，接著在網路上又查了自動化工具和DSL的理論，這才茅塞頓開！雖然大部分都沒看懂，但要做到輕鬆寫出好文檔，足矣！

現在就來談談我是怎麼做到的吧！

要做什麼？

我們的最終目的，是寫出好文件。所以，首先我們要確定：什麼是好文檔。

好文件就如下圖：

上面的文件好在哪裡？
首先，它是文檔，讓你知道它的功能，參數，一目了然；
其次，它是程式，你輸入參數就能馬上看到結果。

所以，我所希望的事，就是在完成程式碼後，可以費很少的力氣，就產生一個像上文中所說的可調試文檔。

我們接下來要做兩件事：
1、產生文件；
2、文件是可偵錯的文檔。

怎麼做？

現在要開始做了，總覺得有些無從下手，那就先從最具體的事情——目前唯一能看得見的可調試API開始分析吧。

我們最後要做出的可調試API是什麼樣的呢？

參考之前的效果圖，簡化一些來說，就是下面這個樣子：

純文字顯示類別名，方法，功能解釋，輸入參數；
有一個執行按鈕；
有一個區域顯示執行結果。

在這個介面中，有哪些是變數呢？

類別名稱

列表項目

方法名

功能說明

參數數量

參數名

執行結果

其中：一個API對應一個類別名，一個方法名，一個功能說明，多個參數名，執行結果是執行後產生的。

模型分析

根據上述結果，我就可以將這個API抽像出一個模型類別了:

一個API包含屬性：類別名，類別檔案所在路徑，方法名，功能說明以及該方法所需輸入的參數。

而一個參數又包含屬性：參數名稱及參數說明。

事件流

接下來分析一下整個事務流程。

一句話流程：
點選「產生」按鈕，產生類別的HTML文件。
這就是我們要做的事情，但說得很不清楚。我們要產生某個類別的某個方法對應的HTML文檔，但一句話沒有說清楚。

現在我們要解釋清楚，於是把它拓展開來，變成一段話：
設定檔中已指定好待生成文件的類別及其方法了，點擊「產生按鈕”， 讀取該設定文件，再依序產生文件。
我們接下去就這樣繼續拓展下去，直到把所有步驟都搞清楚。

最終設計

整個系統共有三類頁面：
功能頁：只有一個產生API的按鈕；

類別清單頁：將類別及其方法列出來，點擊後跳到API頁。

API頁：列出方法說明，可以輸入參數並執行方法，可查看其執行結果。

三類頁面中，第二類類清單頁沒有什麼功能，只牽涉到頁面跳轉，所以只用html實作就行了。
至於功能頁和API頁都採用MVC模式進行設計。

功能頁

MVC結構
Model:API;
View:make_api_template.php;
Controller:create_api.php

MVC呼叫流程
使用者在View層點選「產生」按鈕後，觸發Controller；
Controller中指定了需要產生API的類，並呼叫這些類別中的靜態方法make_api產生了Model;
Controller利用這些Model產生文件

API頁

MVC結構
Model：js程式碼，目前還未形成獨立的model；
View:產生的html頁；
Controller:index.php

MVC呼叫流程
使用者在View層輸入某方法的參數，點選「執行」按鈕後觸發Controller；
Controller根據View頁傳來的參數，執行方法，得到結果後返回給View；
View接收到結果並顯示出來

結語

我實現的版本是CohenBible。

類似的工具很多，prmd，swagger editor， apidocjs，都很好用。
寫這篇文章不是鼓勵大家重複造輪子，但是自己實現過一遍，會有不一樣的收穫。

我為什麼會想到重複造輪子呢？
其實最大的原因就是：真的不太會用上面的幾個工具，只好自己實現，把整個生成文件的流程走了一遍。結果，回過頭再來看上面的工具，竟然拿來就能用了！如果是照官方的教學走，不知道還要花多少時間，哈哈:)

教你如何, 再苦逼, API