資訊專欄INFORMATION COLUMN
摘要：本文寫的是什么平時總要寫文檔。所以，我所希望的事，就是在完成代碼后，可以費(fèi)很少的力氣，就生成一個像上文中所說的可調(diào)試文檔。我們接下來要做兩件事生成文檔文檔是可調(diào)試的文檔。一句話流程點(diǎn)擊生成按鈕，生成類的文檔。
本文寫的是什么？
平時總要寫文檔。不寫，代碼無法維護(hù)，所以不得不寫。但是寫文檔費(fèi)時費(fèi)力，更可怕的是寫完了讀起來還很費(fèi)勁，束之高閣，總感覺時間浪費(fèi)掉了，真是苦不堪言。
一直以來深受“寫文檔”的折磨，偶然看到一篇神文，接著在網(wǎng)上又查了自動化工具和DSL的理論，這才茅塞頓開！雖然大部分都沒看懂，但要想做到輕松寫出好文檔，足矣！
現(xiàn)在就來說說我是怎么辦到的吧！
要做什么？
我們的最終目的，是寫出好文檔。所以，首先我們要確定：什么是好文檔。
好文檔就如下圖所示：
上面的文檔好在哪？
首先，它是文檔，讓你知道它的功能，參數(shù)，一目了然；
其次，它是程序，你輸入?yún)?shù)就能馬上看到結(jié)果。
所以，我所希望的事，就是在完成代碼后，可以費(fèi)很少的力氣，就生成一個像上文中所說的可調(diào)試文檔。
我們接下來要做兩件事：
1、生成文檔；
2、文檔是可調(diào)試的文檔。
怎么做？
現(xiàn)在要開始做了，總感覺有些無從下手，那就先從最具體的事情——目前唯一能看得見的可調(diào)試API開始分析吧。
我們最終要做出的可調(diào)試API是什么樣的呢？
參考之前的效果圖，簡化一些來說，就是下面這個樣子：
純文字顯示類名，方法，功能解釋，輸入?yún)?shù)；
有一個執(zhí)行按鈕；
有一個區(qū)域顯示執(zhí)行結(jié)果。
在這個界面中，有哪些是變量呢？
類名 列表項(xiàng)目 方法名 功能說明 參數(shù)數(shù)量 參數(shù)名 執(zhí)行結(jié)果
其中：一個API對應(yīng)著一個類名，一個方法名，一個功能說明，多個參數(shù)名，執(zhí)行結(jié)果是執(zhí)行后生成的。
模型分析
根據(jù)以上結(jié)果，我就可以將這個API抽象出一個模型類了:
一個API包含屬性：類名，類文件所在路徑，方法名，功能說明以及該方法所需要輸入的參數(shù)。
而一個參數(shù)又包含屬性：參數(shù)名及參數(shù)說明。
事件流
接下來分析一下整個事務(wù)流程。
一句話流程：
點(diǎn)擊“生成”按鈕，生成類的HTML文檔。
這就是我們要做的事情，但是說得很不清楚。我們要生成某個類的某個方法對應(yīng)的HTML文檔，但是一句話沒有說清。
現(xiàn)在我們要解釋清楚，于是把它拓展開來，變成一段話：
配置文件中已指定好待生成文檔的類及其方法了，點(diǎn)擊“生成按鈕”， 讀取該配置文件，再依次生成文檔。
我們接下去就這樣繼續(xù)拓展下去，直到把所有步驟都搞清楚。
最終設(shè)計
整個系統(tǒng)一共有三類頁面：
類清單頁：將類及其方法列出來，點(diǎn)擊后跳轉(zhuǎn)至API頁面。
API頁：列出方法說明，可以輸入?yún)?shù)并執(zhí)行該方法，可查看其執(zhí)行結(jié)果。
三類頁面中，第二類類清單頁沒有什么功能，只涉及到頁面跳轉(zhuǎn)，所以只用html實(shí)現(xiàn)就行了。
至于功能頁和API頁都采用MVC模式進(jìn)行設(shè)計。
功能頁
MVC結(jié)構(gòu)
Model:API；
View:make_api_template.php；
Controller:create_api.php
MVC調(diào)用流程
用戶在View層點(diǎn)擊“生成”按鈕后，觸發(fā)Controller；
Controller中指定了需要生成API的類，并調(diào)用這些類中的靜態(tài)方法make_api生成了Model;
Controller利用這些Model生成文檔
API頁
MVC結(jié)構(gòu)
Model：js代碼，目前還未形成獨(dú)立的model；
View:生成的html頁；
Controller:index.php
MVC調(diào)用流程
用戶在View層輸入某方法的參數(shù)，點(diǎn)擊“執(zhí)行”按鈕后觸發(fā)Controller；
Controller根據(jù)View頁傳來的參數(shù)，執(zhí)行方法，得到結(jié)果后返回給View；
View接收到結(jié)果并將其顯示出來
結(jié)語
我實(shí)現(xiàn)的版本是CohenBible。
類似的工具有很多，prmd，swagger editor， apidocjs，都很好用。
寫這篇文章不是鼓勵大家重復(fù)造輪子，但是自己實(shí)現(xiàn)過一遍，會有不一樣的收獲。
我為什么會想到重復(fù)造輪子呢？
其實(shí)最大的原因就是：真的不太會用上面的幾個工具，只好自己實(shí)現(xiàn)，把整個生成文檔的流程走了一遍。結(jié)果，回過頭再來看上面的工具，竟然拿來就能用了！如果是按官方的教程走，不知道還要花多少時間，哈哈:)
文章版權(quán)歸作者所有，未經(jīng)允許請勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。
轉(zhuǎn)載請注明本文地址：http://systransis.cn/yun/22784.html
摘要：本文寫的是什么平時總要寫文檔。所以，我所希望的事，就是在完成代碼后，可以費(fèi)很少的力氣，就生成一個像上文中所說的可調(diào)試文檔。我們接下來要做兩件事生成文檔文檔是可調(diào)試的文檔。一句話流程點(diǎn)擊生成按鈕，生成類的文檔。 本文寫的是什么？ 平時總要寫文檔。不寫，代碼無法維護(hù)，所以不得不寫。但是寫文檔費(fèi)時費(fèi)力，更可怕的是寫完了讀起來還很費(fèi)勁，束之高閣，總感覺時間浪費(fèi)掉了，真是苦不堪言。 一直以來深受...
摘要：配置配置使用概率抽樣。采樣率定義了對跟蹤跨度進(jìn)行采樣的概率，其值可以介于和含之間。例如，以下配置對象將采樣率更改為即每個跨度都被采樣，并使用協(xié)議將跟蹤發(fā)送到位于的服務(wù)器文件路徑注將采樣率更改為會完全禁用跟蹤。目錄手把手教你學(xué)Dapr - 1. .Net開發(fā)者的大時代手把手教你學(xué)Dapr - 2. 必須知道的概念手把手教你學(xué)Dapr - 3. 使用Dapr運(yùn)行第一個.Net程序手把手教你學(xué)Da...
摘要：適用于，演示這是開發(fā)的一個簡單的可視化庫，它允許你創(chuàng)建所有常用的圖表類型條形圖，樹形圖，折線圖，面積圖等?？梢暂p松地對折線圖和條形圖進(jìn)行混合和匹配以組合不同的數(shù)據(jù)集，這是非常棒的功能。 翻譯：瘋狂的技術(shù)宅原文：https://www.monterail.com/blo... 本文首發(fā)微信公眾號：jingchengyideng歡迎關(guān)注，每天都給你推送新鮮的前端技術(shù)文章 你的程序有多...
摘要：上一篇文章手把手教你如何用構(gòu)建技術(shù)文章聚合平臺一介紹了如何使用搭建的運(yùn)行環(huán)境，并且將與集成，對掘金進(jìn)行技術(shù)文章的抓取，最后可以查看抓取結(jié)果。本篇文章將繼續(xù)講解如何利用編寫一個精簡的聚合平臺，將抓取好的文章內(nèi)容展示出來。 上一篇文章《手把手教你如何用Crawlab構(gòu)建技術(shù)文章聚合平臺(一)》介紹了如何使用搭建Crawlab的運(yùn)行環(huán)境，并且將Puppeteer與Crawlab集成，對掘金、...
閱讀 3609·2021-11-23 09:51
閱讀 2813·2021-11-23 09:51
閱讀 693·2021-10-11 10:59
閱讀 1693·2021-09-08 10:43
閱讀 3244·2021-09-08 09:36
閱讀 3306·2021-09-03 10:30
閱讀 3309·2021-08-21 14:08
閱讀 2214·2021-08-05 09:59
