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