如需加入普元新一代数字化企业云平台研发设计群参与微课堂、架构设计与讨论直播，请直接回复此公众号：“加群 姓名 公司 职位 微信号”。

导读：本文是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）企业架构创新研究院，是专注于企业架构与业务创新领域的研究机构，致力于金融、电信、能源与政务等行业领域的企业软件架构优化设计与 创新研究，以及分布式计算、服务构件技术、可视化技术、业务流程管理、内存计算、企业移动计算、数据治理等领域的技术研究。