使用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，因此没怎么接触，须要你去研究了。