微服务架构实战:Swagger规范RESTful API

导读:本文是EAII微服务系列文章之一随着微服务架构的流行,REST风格也是大势所趋。那么,什么是REST?如何规范我们的RESTFUL API 文档?本文中,作者主要基于以上两个话题进行讨论并探讨在数字化企业云平台实践中如何规范RESTful文档。

REST的引入

随着微服务架构的广泛流行,REST风格受到越来越多的关注。我们先来看一下REST在WIKI的定义及五大关键点:

REST在WIKI的定义

REST stands for Representational State Transfer. It relies on a stateless, client-server, cacheable communications protocol -- and in virtually all cases, the HTTP protocol is used

REST 风格有五大关键点

资源(Resource)

资源的表述(Representation)

状态转移(State Transfer)

统一接口(Uniform Interface)

超文本驱动(Hypertext Driven)

什么是统一接口?

REST要求,必须通过统一的接口来对资源执行各种操作。对于每个资源只能执行一组有限的操作。以HTTP/1.1协议为例,此协议定义了一个操作资源的统一接口,主要包括以下内容:

7个HTTP方法:GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS

HTTP头信息(HTTP Header可以自定义)

HTTP响应状态代码(status code可以自定义)

一套标准的内容协商机制

一套标准的缓存机制

一套标准的客户端身份认证机制

我们遇到的问题…

在开发我们的新一代数字化企业云平台的第一个版本时,前端基于reactJS框架,和后端完全解耦,所有的交互都是通过REST Service完成,同时后端各个领域系统间也是通过REST Service来通信。REST本身虽然有统一的规范,然而对于REST API的管理却没有统一规范,再加上前期时间紧迫,没有足够的资源去做详细的文档说明。API定义的沟通就只能依赖UI和后台开发人员的口头沟通。这里面就存在很多不确定因素

Swagger的引入

如何更优雅且全面地描述我们的RESTful API呢?对API文档管理的规范有很多,比如Swagger,I/O docs,blueprint 等。但是Swagger社区活跃,文档更完善,周围相关的配套产品也更丰富,比如Swager UI,Swagger Editor,并且支持直接生成主流语言的调用代码。

因此,引入Swagger进行Rest API文档管理对项目来说,效率和产出会更高。数字化企业云平台团队经过调研后决定采用Swagger来进行REST API的管理。(注:Microsoft,PayPal等公司也已经引入Swagger 来定义自己的REST API 文档。)

Swagger已经被捐赠给 Open APIInitiative (OAI),属于OAI的成员之一,我们可以简单看下OAI的定义规范:

The goal of the OAIspecification is to define a standard, language-agnostic interface to REST APIswhich allows both humans and computers to discover and understand thecapabilities of the service without access to source code, documentation, orthrough network traffic inspection.

由此可知,Swagger是为了描述一套标准的而且是和语言无关的REST API的规范。对于外部调用者来说,只需通过Swagger文档即可清楚Server端提供的服务,而不需去阅读源码或接口文档说明。官网上有关于Swagger的丰富的资源,包括Swagger Editor,Swagger UI,以及Swagger为各种开发语言提供的SDK。这些资源为REST API 的提供者以及调用者提供了极大的便利。

在确定了引入Swagger后,如何自动根据代码接口的定义来生成Swagger呢? 在数字化企业云平台项目中同时引入了Swagger-Maven-plugin,通过在已有的API接口中添加少量的annotation, 同时配置Pom.xml文件,即可在Maven compile期间自动生成对应的Swagger文件,这大大减少了我们手工维护Swagger文档的工作量,提高工作效率,同时也避免手工维护引起的失误。以数字化企业云平台中Portal领域中的Action的例子来说,这个接口主要作用是提供”在产品管理过程对各个动作的记录”的服务。

在每一个接口中添加必要的annotation,并定义可能出现的error code,如下图所示:

定义好所有的接口后执行mvn compile,生成对应的Swagger文件,将Swagger文件引入到Swagger UI中即可显示所有的REST API的定义:

点击其中的任一API,即可看到API的详细定义,包括request参数,response以及model schema:

跨地域沟通(数字化企业云平台开发地点分布在上海,北京,西安三地)是平台开发中面临的重要挑战之一,引入Swagger后可减少交流成本,规范接口定义,减少手工维护文档的工作,大大降低跨地域沟通带来的风险,让各个领域系统更协调高效地合作,也为数字化企业云平台后续的平台扩展做了坚实有力的支持。

在RESTful架构项目中引入Swagger对REST API进行文档管理的优势是显而易见的,数字化企业云平台后续也将基于自动生成的Swagger文件引入API Mock。

关于作者:

李小飞

EAII-企业架构创新研究院 专家委员

现任普元信息资深开发工程师,为普元新一代数字化企业云平台开发团队一员,负责新一代云平台服务端的支持。曾就职于Emerson Network power和Tibco CDC,并担任Team Leader,期间成功领导多个项目的研发,同时拥有丰富的Cloud经验。爱好:摄影,打球,骑行,成功骑行穿越川藏线。

原文发布于微信公众号 - EAWorld(eaworld)

原文发表时间:2016-05-30

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏JAVA高级架构开发

是什么让程序员成了一份苦逼的工作?

想要学习Java高架构、分布式架构、高可扩展、高性能、高并发、性能优化、Spring boot、Redis、ActiveMQ、Nginx、Mycat、Netty...

870
来自专栏FreeBuf

小技巧:如何发现是否有人用USB偷插你的电脑?

你或许不会知道,咱们其实可以用windows注册表来检测是否曾经有一个特殊的USB设备连接过你的电脑。 验证USB设备的插入的重要性 大家可能不会相信,也许有一...

19910
来自专栏Coding01

跟着《架构探险》学轻量级微服务架构 (一)

微服务概念这两年已经火遍大江南了,但在实际的开发和使用中,用到的还是挺少的,尤其对创业团队来说。

992
来自专栏微信公众号:Java团长

Java软件工程师就业思维图(2016年版)

想要成为合格的Java程序员或工程师到底需要具备哪些专业技能,在面试之前到底需要准备哪些东西呢?面试时面试官想了解你的什么专业技能,以下都是一个合格JAVA软件...

1644
来自专栏Java架构

Java架构师如何冲击年薪40w

4115
来自专栏java一日一条

我是如何成为一个JavaWeb开发者的

  你应该也知道所谓的“全栈”Java开发人员。这是个人的技能集合。一个完整的全栈开发者应该同样胜任前端开发和后端开发的工作。这可能是难度系数最高的一条路了,因...

711
来自专栏IT笔记

单体转向微服务架构-基础篇

5463
来自专栏EAWorld

【详解】为什么选择Spring Boot作为微服务的入门级微框架(PPT)

? 1. Spring Boot是什么,解决哪些问题 1) Spring Boot使编码变简单 2) Spring Boot使配置变简单...

4884
来自专栏全华班

认识工作流- What is Activiti?

阅读文本大概需要 5 分钟。 一、Activiti是什么? ? 我们前文中提到了工作流的概念。工作流是以任务的形式驱动人处理业务或者驱动业务系统...

6668
来自专栏Java架构师学习

Java架构技术怎么学,做到年薪50W会这几点就够了

他们的共同特点是:10 年以上的工作经验,在大公司当过螺丝钉,也在创业公司做过技术 leader,有过一两段不算成功的创业经历。

1242

扫码关注云+社区

领取腾讯云代金券