REST的引入

本文讲的是微服务架构实战：Swagger规范RESTful API，随着微服务架构的广泛流行，REST风格受到越来越多的关注。我们先来看一下REST在WIKI的定义及五大关键点：

什么是统一接口？

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。

原文发布时间为： 2016-05-30
本文作者：李小飞
本文来自云栖社区合作伙伴EAWorld，了解相关信息可以关注EAWorld。