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

本文寫的是什麼？

平時總要寫文檔。不寫，代碼沒法維護，因此不得不寫。可是寫文檔費時費力，更可怕的是寫完了讀起來還很費勁，束之高閣，總感受時間浪費掉了，真是苦不堪言。

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

如今就來講說我是怎麼辦到的吧！

要作什麼？

咱們的最終目的，是寫出好文檔。因此，首先咱們要肯定：什麼是好文檔。

好文檔就以下圖所示：

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

因此，我所但願的事，就是在完成代碼後，能夠費不多的力氣，就生成一個像上文中所說的可調試文檔。

咱們接下來要作兩件事：
一、生成文檔；
二、文檔是可調試的文檔。

怎麼作？

如今要開始作了，總感受有些無從下手，那就先從最具體的事情——目前惟一能看得見的可調試API開始分析吧。

咱們最終要作出的可調試API是什麼樣的呢？

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

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

在這個界面中，有哪些是變量呢？

1. 類名

2. 列表項目

3. 方法名

4. 功能說明

5. 參數數量

6. 參數名

7. 執行結果

其中：一個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，都很好用。
寫這篇文章不是鼓勵你們重複造輪子，可是本身實現過一遍，會有不同的收穫。

我爲何會想到重複造輪子呢？
其實最大的緣由就是：真的不太會用上面的幾個工具，只好本身實現，把整個生成文檔的流程走了一遍。結果，回過頭再來看上面的工具，居然拿來就能用了！若是是按官方的教程走，不知道還要花多少時間，哈哈:)