普元雲計算-微服務架構實戰：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的官方微信帳號。