普元云计算-微服务架构实战：Swagger规范RESTful API

转载本文需注明出处：EAII企业架构创新研究院，违者必究。如需加入微信群参与微课堂、架构设计与讨论直播请直接回复公众号：“EAII企业架构创新研究院”。（微信号：eaworld）

 

导读：本文是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经验。爱好：摄影，打球，骑行，成功骑行穿越川藏线。

 

 

关于EAII

EAII（Enterprise Architecture Innovation Institute）企业架构创新研究院，是专一于企业架构与业务创新领域的研究机构，致力于金融、电信、能源与政务等行业领域的企业软件架构优化设计与 创新研究，以及分布式计算、服务构件技术、可视化技术、业务流程管理、内存计算、企业移动计算、数据治理等领域的技术研究。

 

eaworld项目（微信号：eaworld，长按二维码关注）

eaworld是EAII的官方微信帐号。