使用Swagger輔助開發Fabric Application的Web API

前面的幾篇博客，咱們已經把Fabric環境搭建好了，也可使用Go開發ChainCode了，那麼咱們在ChainCode開發完畢後，能夠經過CLI來測試ChainCode的正確性，ChainCode開發後，接下來就是關於Application的編寫了。

Application分爲2部分，一部分是關於後來業務邏輯的，也就是Web API，通常是經過RESTful的形式提供，另一部分就是UI，固然大多數狀況下都是GUI，也就是網站前端，Windows程序，APP之類的。關於前端，我因爲沒啥藝術細胞，作出來的界面很醜，因此也就揚長避短，不多作前端開發，專一於後臺業務邏輯的實現。

一 簡介

在Web API的開發中，業內最知名的工具就是Swagger了，這簡直就是一件神器啊！我以前在C#開發的時候就使用ABP框架，用到了Swagger，在試着使用Go的Web開發框架Beego的時候也看到了Swagger，如今使用Node開發，想不到又用到Swagger，只能說明Swagger的跨平臺跨語言的能力太強了。Swagger能夠幫助咱們把API文檔化，方便進行測試。

Swagger的開發方式有2種：

1. 使用Web開發框架中遷移過來的Swagger庫，也就是先代碼，後生成API文檔的模式。好比ABP框架中就是，咱們只須要在ApiController中定義好接口和註釋好，其框架就能夠幫咱們生成Swagger界面。
2. 使用Swagger的yaml文件定義API接口，定義好後，再使用Swagger官方提供的CodeGen生成對應語言的代碼。

第一種開發方式要看你使用的Web框架的支持狀況，接下來咱們要講的就是第二種開發方式。

二 編寫Swagger YAML

官方已經給我提供一個寵物商店的示例，並提供了強大的語法檢查和預覽功能，那就是Swagger Editor，咱們直接訪問http://editor.swagger.io/ 就能夠看到。若是因爲某些神祕的力量，形成訪問特別緩慢或者沒法訪問，咱們也能夠下載Swagger Editor的Image到本地來運行。

直接在安裝了Docker的環境中運行以下命令：

docker pull swaggerapi/swagger-editor
docker run -p 80:8080 swaggerapi/swagger-editor

而後就能夠訪問http://{Your_Server_IP}。

不論是在線的Editor或者是本地部署的Docker，咱們最終看到是這樣一個界面：

左邊窗口就是咱們要編輯的YAML文件的內容，右邊窗口就是預覽的API文檔的效果。

關於YAML文件，其實可讀性仍是很強的，大部分都不須要解釋就知道是什麼意思，下面我來着重介紹如下幾個比較重要的元素：

1. host&basePath

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測試時候的調用地址。

2. tags

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能夠看到效果。

3. paths

這是最主要的配置元素。主要的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對應的銀行未找到 

4. securityDefinitions

這是安全定義模塊，在這裏能夠定義咱們WebAPI的安全認證方式，好比:

• Basic Authentication
• API Keys
• Bearer Authentication
• OAuth 2.0
• OpenID Connect Discovery
• Cookie Authentication

這裏面這麼多種認證方式，不少我也沒用過，瞭解不深，我主要用的是Bearer和OAuth 2.0，具體設置你們能夠參考文檔：

https://swagger.io/docs/specification/authentication/

5. definitions

這裏是定義咱們在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，因此沒怎麼接觸，須要你去研究了。