转载本文需注明出处：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：