如何利用 Swagger 消除前後端分離的障礙？

【不要錯過文末彩蛋】

編輯 奧格瑞姆

前言

隨著後端技術的日漸成熟和前端框架的異軍突起，前後端分離幾乎已經企業開發必須要選擇的方向。

但是採用了 JSP、Struts2、SpringMVC 等技術的項目在實現前後端分離時，由於 Web 容器的使用，使得前端開發人員無法專註於前台展示，分離起來困難重重。

RESTful 架構的引入，讓電腦端、移動端、第三方系統的數據交互和流程式控制制更加便捷，也使得前後端分離成為可能。

但是隨著項目的推進，眾多的 API 如果管理不當，在項目集成時，又將陷入泥潭。而 Swagger 的出現專註於為 API 提供可視化文檔，便於前後端開發人員對接。

前後端分離很重要？對於項目

前端界面注重展示效果，希望有更好的交互性和快速的響應。後台服務專註於提供數據，希望有穩定的性能，需要確保數據的安全，降低系統的瓶頸。

在業務邏輯複雜的系統里，最難維護的就是那些前後端混雜在一起的代碼。我所在的項目組，搜索業務的代碼原來是用 JSP 寫的，代碼風格相對隨意，在數次艱難的 bug 修復後，終於全部廢棄了。

對於公司

前後端界定不清，公司的招聘可能難度更大。full stack的工程師可遇而不可求，就算直接培養也很難使其在各個領域都成為大神。

而且 full stack 意味著他掌握的業務線越長，一旦離職，會對整個團隊造成較大的影響。職責清楚，分工明確，意味著公司招聘更簡單。

對於個人

前端人員有著自己的開發流程，有更適合的構建工具和測試方法，他們不希望用 Maven 構建項目、不希望用 Eclipse 編寫代碼，往往需要把用戶體驗放在第一位。

後端人員也有自己的開發習慣，他們不想用 Gulp 構建項目，也不會選擇 WebStrom 調試代碼，整天圍繞著數據存貯與提取，數據計算，數據安全，往往把數據放在第一位。

前後端分離就是為了提高效率，提高項目的開發效率，提高公司的招聘效率，提高開發人員的學習效率。

然而，以API形式解耦前後端開發過程，通過 RESTFul 方式通信，項目集成將是繞不開的話題。開源項目 swagger 正是在這樣的背景下因運而生。

Swagger 初步認知Swagger 項目

Swagger 是很多產品的總稱。包含最核心的規範 Swagger Specification，編輯器 Swagger Editor，圖形界面 Swagger UI，代碼生成器 Swagger Codegen，成熟的產品 SwaggerHub 等。

Swagger 的主要作用是描述 RESTful API，生成互動式文檔，便於前後端開發人員查看請求信息和響應數據。

Swagger 與 OpenAPI

Swagger 項目最初由非營利組織Wordnik於2010年發起的， 之後於2015年轉交給了 SmartBear，這家 SmartBear 公司專註於開發測試和性能工具。

隨後 SmartBear 又在 Linux 基金會下創建了一個 OpenAPI Initiative(OAI) 項目，並捐獻出了 Swagger。

由於 Google，IBM，Microsoft 等公司對 OpenAPI Initiative 的持續貢獻，OAI 日漸成熟，Swagger 又被稱之為 OpenAPI。

我們目前常用 Swagger 的版本為 Swagger 2.0，它的下一版不是 Swagger 3.0，而是 OpenAPI 3.0

Swagger 快速上手

要了解 Swagger，必須知道一些常用的 Swagger 規範，官方建議使用 JSON 格式或者 YAML 語法來編寫這一規約，我更傾向於YAML，這種格式更容易書寫和閱讀。

Swagger Editor 編輯器

Node.js 不是必須的，你也可以直接下載 Swagger Editor 的源代碼

https://github.com/swagger-api/swagger-editor。

解壓以後，用本地瀏覽器打開 ./dist/index.htm l即可。

Swagger Editor 只是一款編輯器，學習 Swagger 不一定要用到它。你也可以用記事本或者Eclipse等工具編輯 Swagger 規約。

不過 Swagger Editor 有如下幾個有點：1. 代碼提示與代碼高亮；2. 語法檢查； 3. 實時預覽，左邊寫code，右邊實時生成UI。

Swagger Specification 規約

下面是我用 Swagger 規範寫的一個「Hello World」，使用 Swagger Editor 編輯，可以很快得到下面的文檔，而且可以在右側看到生成的圖形化界面。

首先是 YAML 格式，如 swagger.yml：

如果選擇 JSON 格式，如 swagger.json：

{ "swagger":"2.0", "info":{ "version":"1.0.0", "title":"My Hello world", "description":"description example"}, "schemes":["http"], "host":"test.com", "basePath":"/", "paths":{ "/hello":{ "get":{ "summary":"hello, world", "description":"My first swagger.", "parameters":[ { "in":"query", "name":"name", "description":"The name of the person", "type":"string"} ], "responses":{ "200":{ "description":"A list of Person", }}}}}}

對比發現，YAML 格式看起來更舒服，寫起來也更加便捷。當然，已經有很多工具可以實現 YAML-JSON 之間的轉換，用自己喜歡的風格即可。

規範的內容本身很容易理解，配合 Swagger Editor 很容易能寫出對用的API文檔。如果需要更詳細的說明，可以在官網的 doc 頁面找到。

Swagger UI 互動式圖形化界面

剛才得到的 Swagger 規約可以方便地在團隊間編輯，傳輸，但是不夠直觀，於是有了Swagger-UI。

它是為基於 Swagger 規範的 API 生成基於純粹 HTML，javascript，css 的在線可視化文檔，同時也能成為 API 的在線測試工具。

你可以在 GitHub 上得到其源代碼 https://github.com/wordnik/swagger-ui。其中 ./dist/* 中的文件是生成好的文件，可以直接使用，你也可以修改源代碼，然後使用 Node 運行。

可以看到最新的版本於2017-09-15發布，該版本最大的優勢就是支持OpenAPI 3.0

我們得到的文件 swagger-ui/dist/index.html 中有如下代碼片段，將其中的url替換成自己的文件，如url: "swagger.yml"，用瀏覽器打開index.html，就能看到漂亮的文檔說明。

Swagger 與 Spring Boot

如果你的項目運用了 Microservice，引入了 Spring Boot，構建的 RESTful API 通過手工管理簡直是噩夢。如今，Swagger 與 Spring Boot 的無縫對接，簡直就是不願寫文檔的猿類的福音。

需要的依賴

在 pom.xml 中需要引入支持 Swagger 所需要的依賴包。

io.springfoxspringfox-swagger22.2.2io.springfoxspringfox-swagger-ui2.2.2

需要的配置

將 Swagger 整合到項目中，需要在啟動類 Application.java 同級目錄下創建一個配置類，名稱任意，如 Swagger.java

這裡需要制定一個 basePackage( )，不然整個項目中所有的API都會生成文檔，包括 Spring 自己的 service。

測試一下

啟動 Spring Boot 程序後，訪問：

http://localhost:8080/swagger-ui.html

將看到類似 Swagger UI 的效果。點擊 Try it out 可以測試 API 的是否正常工作。

Swagger 與你有多近

基於前後端分離的契約，無論你是後端開發，前端開發，測試人員，你都可以體驗到 Swagger 的眾多好處。

生成互動式文檔：一般開發人員容易忽視API文檔，程序員最不喜歡的就是寫文檔，但是總是抱怨這個維護的程序怎麼沒有文檔。

人類可讀與機器可讀：選擇 JSON 和 YAML 格式作為 Swagger 的規範格式不是偶然的結果，這樣可以讓方便更多的用戶編輯文檔，分享分檔，可以很方便地在各種編程語言之間直接調用或相互轉換。

無論是手動編寫 Swagger 規範，還是代碼自動生成 Swagger 規約，漂亮的文檔只是幫助我們更好的完成開發任務，Swagger 不是必須的，但，可能是必要的。

前後端分離了，接下來，就看你的了！

彩蛋

重磅 Chat

《高效學習，快速變現：不走彎路的五大學習策略》

分享人：

Seaborn Lee，一名會在 B 站直播寫代碼，會玩雜耍球、彈 Ukulele、極限健身、跑步、寫段子、畫畫、翻譯、寫作、演講、培訓的程序員。喜歡用編程實現自己的想法，在 Android 市場上賺過錢，有多次創業經歷。

擅長學習，習慣養成，時間管理。身體力行地影響他人做出積極的改變！目前就職於 ThoughtWorks，致力於傳播快樂高效的編程理念。業餘創立軟體匠藝社區 CodingStyle.cn，組織超過30場技術活動。

Chat簡介：

說到學習呀，真是頭大喲：

碎片化，沒有較長的連續時間來學習

難專註，捧起書，手機卻在召喚：來呀，快活呀~ 反正有，大把時光~

做不到，看了很多書，生活中卻做不到

然並卵，學了方法和工具，找不到使用場景

效率低，學習速度跟不上知識產生的速度

記不牢，學習速度趕不上遺忘速度

在這個知識泛濫、跨界競爭的年代，學習能力才是核心競爭力。你想想，過去一周，有沒有哪一件工作是不需要學習就能完成的？

儘管如此重要，大部分人卻沒研究過學習這件事，以為上下班路上打開「得到」聽本書，就是碎片時間終身學習者了。

想要免費參與本場 Chat ？

喜歡這篇文章嗎？立刻分享出去讓更多人知道吧！

本站內容充實豐富，博大精深，小編精選每日熱門資訊，隨時更新，點擊「搶先收到最新資訊」瀏覽吧！

請您繼續閱讀更多來自 GitChat技術雜談 的精彩文章: