前面的幾篇博客,咱們已經把Fabric環境搭建好了,也可使用Go開發ChainCode了,那麼咱們在ChainCode開發完畢後,能夠經過CLI來測試ChainCode的正確性,ChainCode開發後,接下來就是關於Application的編寫了。前端
Application分爲2部分,一部分是關於後來業務邏輯的,也就是Web API,通常是經過RESTful的形式提供,另一部分就是UI,固然大多數狀況下都是GUI,也就是網站前端,Windows程序,APP之類的。關於前端,我因爲沒啥藝術細胞,作出來的界面很醜,因此也就揚長避短,不多作前端開發,專一於後臺業務邏輯的實現。node
在Web API的開發中,業內最知名的工具就是Swagger了,這簡直就是一件神器啊!我以前在C#開發的時候就使用ABP框架,用到了Swagger,在試着使用Go的Web開發框架Beego的時候也看到了Swagger,如今使用Node開發,想不到又用到Swagger,只能說明Swagger的跨平臺跨語言的能力太強了。Swagger能夠幫助咱們把API文檔化,方便進行測試。docker
Swagger的開發方式有2種:npm
第一種開發方式要看你使用的Web框架的支持狀況,接下來咱們要講的就是第二種開發方式。json
官方已經給我提供一個寵物商店的示例,並提供了強大的語法檢查和預覽功能,那就是Swagger Editor,咱們直接訪問http://editor.swagger.io/ 就能夠看到。若是因爲某些神祕的力量,形成訪問特別緩慢或者沒法訪問,咱們也能夠下載Swagger Editor的Image到本地來運行。api
直接在安裝了Docker的環境中運行以下命令:瀏覽器
docker pull swaggerapi/swagger-editor docker run -p 80:8080 swaggerapi/swagger-editor
而後就能夠訪問http://{Your_Server_IP}。
不論是在線的Editor或者是本地部署的Docker,咱們最終看到是這樣一個界面:安全
左邊窗口就是咱們要編輯的YAML文件的內容,右邊窗口就是預覽的API文檔的效果。服務器
關於YAML文件,其實可讀性仍是很強的,大部分都不須要解釋就知道是什麼意思,下面我來着重介紹如下幾個比較重要的元素:app
host是指定了咱們的API服務器的地址,也就是咱們部署了Web API時,是部署在哪一個Server上。若是咱們是本地開發,並且使用了自定義端口,好比8080,那麼須要改爲localhost:8080。
basePath是指定API的虛擬目錄,好比咱們有個得到全部用戶列表的API是:GET /User,若是咱們設定了basePath是「/api」,那麼咱們要訪問的路徑應該是:
GET http://localhost:8080/api/User
固然,若是咱們要更規範,好比把API版本也放進去,那麼咱們能夠設置basePath爲」/api/v1」,因而咱們的訪問路徑就是:
GET http://localhost:8080/api/v1/User
這個basePath參數涉及到服務器端api路由的生成,而host涉及到各個API測試時候的調用地址。
Tags是用於咱們對大量的API進行分區用的,說簡單點就是爲了大量的API可以更好看,更容易查找。咱們能夠爲tag添加註釋,使得API文檔更容易讀懂。
Tags不涉及到後臺的改變,每個具體的API均可以指定屬於哪一個(或者哪幾個tag),而後在Swagger顯示的時候,會將這些API歸到所屬的Tag下面去。
【注意:YAML文件格式嚴格要求縮進,就像Python同樣,因此若是咱們在添加元素的時候必定要注意縮進是否正確。】
好比咱們新建一個Tag叫Bank,而後增長一點對這個Tag的描述,接下來咱們再到/pet post下面,能夠把tags增長一行,寫爲銀行,而後就能夠看到右邊的預覽窗口更新了,顯示了銀行這個Tag相關的API:
若是沒有刷新,咱們能夠點擊上面菜單的Edit->Convert to YAML能夠看到效果。
這是最主要的配置元素。主要的API配置都在這個環節。下面一級一級的講解。
第一級是URL,以/開頭,URL中能夠指定參數。好比咱們要得到某個bankId對應的銀行信息,那麼URL就是
/bank/{bankId}
第二級是HTTP方法,咱們在WebAPI中主要用到的方法有:查詢get,建立post,修改put和刪除delete。由於咱們是要查詢某個銀行ID對應的銀行信息,因此咱們在這一級輸入get
第三級有多個元素,分別是:
tags,說明這個API是屬於哪一個Tag的。
summary,對該接口的簡單描述,一句話便可。
description,顧名思義,是接口的介紹,能夠寫的詳細一點。
operationId,這是對應的後臺的方法名,Swagger的路由就能夠根據URL和這裏的operationId找到對應的Action方法。
consumes,是客戶端往服務器傳的時候,支持什麼類型,通常咱們只須要保留json便可,能夠把xml刪除。若是是get方法,不須要該元素。
produces,就是服務器在返回給客戶端數據的時候,是什麼樣式的數據,咱們仍然保留json便可。
parameters就是具體的參數,這裏的設置比較複雜,包括指定參數是在URL中仍是在Body中,傳入的參數是什麼類型的,是否必須有該參數,對該參數的描述等。若是參數是一個對象,那麼須要添加對該對象類型的引用,而對象的定義在後面definitions節點中。
responses是服務器返回的HTTP Code有哪些。每一種狀態碼錶示什麼意思。
security是指定該接口的安全檢查方式,若是沒有設置,那麼就是匿名訪問。其引用的是securityDefinitions中的定義。
x-swagger-router-controller,這是一個擴展元素,用來指定該URL對應的後臺的Controller名。
結合上面介紹的,咱們自定義一個根據ID獲取Bank對象的YAML內容以下:
/bank/{bankId} : get: tags: - Bank summary: 根據銀行ID得到銀行基本信息 description: 詳細描述 operationId: getBankById produces: - application/json parameters: - name: bankId in: path description: 銀行對象的主鍵ID required: true type: integer format: int64 responses: '200': description: 找到銀行 schema: $ref: '#/definitions/Bank' '400': description: 無效的ID '404': description: ID對應的銀行未找到
這是安全定義模塊,在這裏能夠定義咱們WebAPI的安全認證方式,好比:
這裏面這麼多種認證方式,不少我也沒用過,瞭解不深,我主要用的是Bearer和OAuth 2.0,具體設置你們能夠參考文檔:
https://swagger.io/docs/specification/authentication/
這裏是定義咱們在API中會涉及到哪些JSON對象的地方。也就是說咱們在API中要POST上去的JSON或者經過GET由服務器返回的JSON,其對象都在這裏定義,上面的步驟直接引用這裏的定義便可。
好比咱們上面須要引用到Bank對象,那麼咱們在這裏定義以下:
Bank: type: object properties: id: type: integer format: int32 name: type: string
若是是對象嵌套引用了其餘對象,也能夠經過$ref的方式引用過去,咱們能夠參考官方示例中的Pet對象,就引用了Category。
以上各個元素我只是簡單的講解,對於各類深刻的用法,你們能夠參考官方文檔:https://swagger.io/docs/
只要咱們預覽右邊的代碼沒有報任何錯誤,那麼咱們就能夠生成對於的後臺代碼了。這裏由於Fabric SDK是Node的,因此咱們的Web API也是使用Node來開發。咱們點擊Generate Server菜單下的nodejs-server選項:
系統會下載一個壓縮包,該壓縮包解壓後就是咱們的Web API Node項目。在安裝了Node的機器上,咱們使用如下命令,安裝項目所依賴的包:
npm install --registry=https://registry.npm.taobao.org
安裝完畢後,運行如下命令:
npm start
咱們能夠看到網站地址是:http://localhost:8080/docs
打開瀏覽器,訪問這個網站,就能夠看到Swagger生成的UI,並看到咱們自定義的獲取銀行對象的方法。
下面,咱們來試一試傳入參數1,並調用該API,能夠看到這樣的結果:
這裏返回的是Swagger給咱們Mock的一個假結果,若是咱們要返回真實的結果,那麼須要在Controllers文件夾中找到BankService.js,看到以下的內容:
'use strict'; exports.getBankById = function(args, res, next) { /** * 根據銀行ID得到銀行基本信息 * 詳細描述 * * bankId Integer 銀行對象的主鍵ID * returns Bank **/ var examples = {}; examples['application/json'] = { "name" : "aeiou", "id" : 0 }; if (Object.keys(examples).length > 0) { res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify(examples[Object.keys(examples)[0]] || {}, null, 2)); } else { res.end(); } }
將Mock代碼部分刪除,將咱們真實的業務邏輯寫進去便可完成咱們的WebAPI的開發工做。
Swagger真的不愧是Web API開發的神器,太好用了。另外官方還有SwaggerHub,支持多人協做編寫YAML文檔,不過是收費的。咱們在項目中其實能夠經過Git來管理yaml文件,由於該文件存在於WebAPI項目的api文件夾中,因此其實你們能夠共同編輯,而後使用Git來合併衝突。另外Swagger還有Client,看了一些支持各類語言,各類框架,各類APP開發,真是太強大了,我因爲不開發GUI,因此沒怎麼接觸,須要你去研究了。