使用Swagger辅助开发Fabric Application的Web API

简介: 前面的几篇博客,我们已经把Fabric环境搭建好了,也可以使用Go开发ChainCode了,那么我们在ChainCode开发完毕后,可以通过CLI来测试ChainCode的正确性,ChainCode开发后,接下来就是关于Application的编写了。

前面的几篇博客,我们已经把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,我们最终看到是这样一个界面:

image

左边窗口就是我们要编辑的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:

image

如果没有刷新,我们可以点击上面菜单的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选项:

image

系统会下载一个压缩包,该压缩包解压后就是我们的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,所以没怎么接触,需要你去研究了。

【本文章出自 博客园深蓝居,转载请注明作者出处,如果您觉得博主的文章对您有很大帮助,欢迎点击右侧打赏按钮对博主进行打赏。】
打个招聘广告,博主正在主导开发一个跨链区块链项目:PalletOne,一直在招Go程序员,待遇丰厚,坐标北京酒仙桥,希望有识之士加入!
目录
相关文章
|
2天前
|
前端开发 API 开发者
Python Web开发者必看!AJAX、Fetch API实战技巧,让前后端交互如丝般顺滑!
【7月更文挑战第13天】在Web开发中,AJAX和Fetch API是实现页面无刷新数据交换的关键。在Flask博客系统中,通过创建获取评论的GET路由,我们可以展示使用AJAX和Fetch API的前端实现。AJAX通过XMLHttpRequest发送请求,处理响应并在成功时更新DOM。Fetch API则使用Promise简化异步操作,代码更现代。这两个工具都能实现不刷新页面查看评论,Fetch API的语法更简洁,错误处理更直观。掌握这些技巧能提升Python Web项目的用户体验和开发效率。
15 7
|
2天前
|
API 数据库 开发者
逆袭之路!Django/Flask助你成为Web开发界的璀璨新星!
【7月更文挑战第13天】在Python Web开发中,Django和Flask各具优势。Django适合快速构建大型项目,如在线书店,其ORM和内置功能让复杂应用轻松上手。Flask则以其轻量和灵活性见长,适用于个人博客等小型应用。选择框架应根据项目需求和个人偏好,两者都能助开发者在Web开发领域大放异彩。
11 2
|
3天前
|
安全 大数据 编译器
PHP 8: 探索新特性及其对现代Web开发的影响
在这篇文章中,我们将深入探讨PHP 8的最新特性,包括JIT编译器、联合类型、匹配表达式等,并分析这些更新如何影响现代Web开发。通过具体示例和代码片段,本文旨在为开发者提供一个清晰的指南,以便更好地利用PHP 8的新功能优化和加速他们的应用程序。
10 2
|
3天前
|
编译器 测试技术 PHP
深入理解PHP 7的新特性及其对现代Web开发的影响
【7月更文挑战第12天】本文将探讨PHP 7版本中引入的关键改进和新增功能,以及这些变化如何优化了性能、提升了代码的可维护性,并促进了现代Web开发的最佳实践。通过具体示例,我们将深入了解这些新特性在日常开发中的应用,以及它们为开发者带来的实际益处。
10 2
|
3天前
|
数据库 开发者 Python
从菜鸟到大神,Django/Flask 让你秒变 Web 开发界的‘头号玩家’!
【7月更文挑战第12天】在Python Web开发中,Django和Flask框架各具特色。Flask轻量灵活,适合快速搭建简单应用,如博客,基本代码仅需几行。Django则功能全面,适用于复杂项目,如电商网站,内置ORM和管理后台。两者都助力开发者从新手进阶。选择取决于项目需求和个人偏好。学习和实践这两个框架,能助你成为Web开发专家。
|
3天前
|
PHP 开发者
PHP 8 新特性及其对现代Web开发的影响
PHP 8作为最新版本,引入了一系列强大的新特性和改进,这些变化不仅仅是语言本身的提升,更深刻地影响了现代Web开发的方式和效率。本文将深入探讨PHP 8的关键特性,分析其在开发实践中的应用和优势,帮助开发者更好地理解和利用这些新特性。 【7月更文挑战第12天】
10 1
|
7天前
|
安全 编译器 PHP
深入理解PHP 8的新特性及其对现代Web开发的影响
【7月更文挑战第8天】随着PHP 8的发布,这个广受欢迎的服务器端脚本语言迎来了重大更新,带来了性能提升和更现代化的编程特性。本文将探索PHP 8中的新特性,并分析它们如何改变开发者构建和维护Web应用的方式,同时指出这些变化对现有项目升级可能带来的挑战与机遇。
|
6天前
|
前端开发 JavaScript NoSQL
"从零到一:全方位解析现代Web开发技术栈
【7月更文挑战第9天】在当今快速发展的互联网时代,Web开发技术日新月异,为开发者提供了前所未有的创新空间。本文将从基础到高级,全面解析现代Web开发技术栈,帮助初学者或希望升级技能树的开发者构建稳固的知识体系。我们将探讨前端、后端以及全栈开发的关键技术,并通过一个简单的项目示例来演示这些技术的实际应用。
28 1
|
10天前
|
设计模式 Rust 安全
深入理解PHP 7的新特性及其对现代Web开发的影响
本文通过数据驱动的分析,探讨了PHP 7的发布如何革新了Web开发的面貌。文章首先概述了PHP 7带来的性能提升与新特性,然后通过实际案例和性能测试数据,详细讨论了这些新特性对提高代码效率、增强安全性和支持现代编程范式的具体影响。最后,文章将评估PHP 7在当前Web开发环境中的地位,并对其未来的发展做出展望。
|
1天前
|
XML 前端开发 API
颠覆传统!AJAX、Fetch API与Python后端,开启Web开发新篇章!
【7月更文挑战第14天】Web开发中,AJAX作为异步通信先驱,与新兴的Fetch API一起革新交互体验。Fetch基于Promise,简化了请求处理。Python后端,如Flask,提供稳定支撑。这三者的融合,推动Web应用达到新高度,实现高效、实时交互。通过示例展示,我们看到从发送请求到更新UI的流畅过程,以及Python如何轻松返回JSON数据。这种组合揭示了现代Web开发的潜力和魅力。
8 0