国产xxxx99真实实拍_久久不雅视频_高清韩国a级特黄毛片_嗯老师别我我受不了了小说

資訊專欄INFORMATION COLUMN

API 教你如何生成可調試的API文檔

KaltZK / 3528人閱讀

摘要：本文寫的是什么平時總要寫文檔。所以，我所希望的事，就是在完成代碼后，可以費很少的力氣，就生成一個像上文中所說的可調試文檔。我們接下來要做兩件事生成文檔文檔是可調試的文檔。一句話流程點擊生成按鈕，生成類的文檔。

本文寫的是什么？

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

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

現在就來說說我是怎么辦到的吧！
要做什么？

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

好文檔就如下圖所示：

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

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

我們接下來要做兩件事：
1、生成文檔；
2、文檔是可調試的文檔。
怎么做？

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

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

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

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

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

類名

列表項目

方法名

功能說明

參數數量

參數名

執行結果

其中：一個API對應著一個類名，一個方法名，一個功能說明，多個參數名，執行結果是執行后生成的。
模型分析

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

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

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

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

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

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

整個系統一共有三類頁面：

類清單頁：將類及其方法列出來，點擊后跳轉至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，都很好用。
寫這篇文章不是鼓勵大家重復造輪子，但是自己實現過一遍，會有不一樣的收獲。

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

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/22784.html

相關文章

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

    摘要：本文寫的是什么平時總要寫文檔。所以，我所希望的事，就是在完成代碼后，可以費很少的力氣，就生成一個像上文中所說的可調試文檔。我們接下來要做兩件事生成文檔文檔是可調試的文檔。一句話流程點擊生成按鈕，生成類的文檔。 本文寫的是什么？ 平時總要寫文檔。不寫，代碼無法維護，所以不得不寫。但是寫文檔費時費力，更可怕的是寫完了讀起來還很費勁，束之高閣，總感覺時間浪費掉了，真是苦不堪言。 一直以來深受...

    SegmentFault 評論0 收藏0

  • 手把手教你學Dapr

    摘要：配置配置使用概率抽樣。采樣率定義了對跟蹤跨度進行采樣的概率，其值可以介于和含之間。例如，以下配置對象將采樣率更改為即每個跨度都被采樣，并使用協議將跟蹤發送到位于的服務器文件路徑注將采樣率更改為會完全禁用跟蹤。目錄手把手教你學Dapr - 1. .Net開發者的大時代手把手教你學Dapr - 2. 必須知道的概念手把手教你學Dapr - 3. 使用Dapr運行第一個.Net程序手把手教你學Da...

    qqlcbb 評論0 收藏0

  • 14個最好的 JavaScript 數據可視化庫

    摘要：適用于，演示這是開發的一個簡單的可視化庫，它允許你創建所有常用的圖表類型條形圖，樹形圖，折線圖，面積圖等。可以輕松地對折線圖和條形圖進行混合和匹配以組合不同的數據集，這是非常棒的功能。 翻譯：瘋狂的技術宅原文：https://www.monterail.com/blo... 本文首發微信公眾號：jingchengyideng歡迎關注，每天都給你推送新鮮的前端技術文章 你的程序有多...

    Mertens 評論0 收藏0

  • 淺析WSGI

    摘要：也就是說，是連接服務器和應用服務器的橋梁。目前實現的中，有兩個角色分別是和。是一個可調用對象，它包含了一個表示響應狀態的字符串和一個響應的列表以及一個用于出錯返回的信息，具體參數包含及詳情請點這里。可以被連接在一起，由此產生的鏈通常被稱為。 首先，什么是WSGI？ WSGI, 全稱為 Web Server Gateway Interface。 它不是什么框架，它是一個規范，但是作為一個...

    王偉廷 評論0 收藏0

  • 手把手教你如何用Crawlab構建技術文章聚合平臺(二)

    摘要：上一篇文章手把手教你如何用構建技術文章聚合平臺一介紹了如何使用搭建的運行環境，并且將與集成，對掘金進行技術文章的抓取，最后可以查看抓取結果。本篇文章將繼續講解如何利用編寫一個精簡的聚合平臺，將抓取好的文章內容展示出來。 上一篇文章《手把手教你如何用Crawlab構建技術文章聚合平臺(一)》介紹了如何使用搭建Crawlab的運行環境，并且將Puppeteer與Crawlab集成，對掘金、...

    zhunjiee 評論0 收藏0

發表評論

0條評論

最新活動
閱讀需要支付1元查看
<