問題

首先我們先來說說傳統(tǒng)開發(fā)中前后端協(xié)同開發(fā)出現(xiàn)的一些問題。
不管是前端還是后端開發(fā)，應(yīng)該都多少被接口文檔折磨過。前端經(jīng)常抱怨后端給的接口文檔與實際情況不一致，后端又覺得編寫及維護(hù)接口文檔會耗費(fèi)不少精力，經(jīng)常來不及更新。其實無論是前端調(diào)用后端，還是后端調(diào)用后端，都期望有一個好的接口文檔。但是這個接口文檔對于程序員來說，就跟注釋一樣，經(jīng)常會抱怨別人寫的代碼沒有寫注釋，然而自己寫起代碼起來，最討厭的，也是寫注釋。所以僅僅只通過強(qiáng)制來規(guī)范大家是不夠的，隨著時間推移，版本迭代，接口文檔往往很容易就跟不上代碼了。

Swagger是什么？

正因為有這些問題的出現(xiàn)，Swagger才得以誕生，你可以把Swagger看做是一套規(guī)范，通過這套規(guī)范，你只需要按照它的規(guī)范去定義接口及接口相關(guān)的信息，再通過Swagger衍生出來的一系列項目和工具，就可以做到生成各種格式的接口文檔，生成多種語言的客戶端和服務(wù)端的代碼，以及在線接口調(diào)試頁面等等。這樣，如果按照新的開發(fā)模式，在開發(fā)新版本或者迭代版本的時候，只需要更新Swagger描述文件，就可以自動生成接口文檔和客戶端服務(wù)端代碼，做到調(diào)用端代碼、服務(wù)端代碼以及接口文檔的一致性。
但即便如此，對于許多開發(fā)來說，編寫這個yml或json格式的描述文件，本身也是有一定負(fù)擔(dān)的工作，所以作為Java屆服務(wù)端的大一統(tǒng)框架Spring，迅速將Swagger規(guī)范納入自身的標(biāo)準(zhǔn)，建立了Spring-swagger項目，后面改成了現(xiàn)在的Springfox。通過在項目中引入Springfox，可以掃描相關(guān)的代碼，生成該描述文件，進(jìn)而生成與代碼一致的接口文檔和客戶端代碼。這種通過代碼生成接口文檔的形式，在后面需求持續(xù)迭代的項目中，顯得尤為重要和高效。

主要開源工具

Swagger Codegen

通過Codegen 可以將描述文件生成html格式和cwiki形式的接口文檔，同時也能生成多鐘語言的服務(wù)端和客戶端的代碼。支持通過jar包，docker，node等方式在本地化執(zhí)行生成。也可以在后面的Swagger Editor中在線生成。

Swagger UI

提供了一個可視化的UI頁面展示描述文件。接口的調(diào)用方、測試、項目經(jīng)理等都可以在該頁面中對相關(guān)接口進(jìn)行查閱和做一些簡單的接口請求。該項目支持在線導(dǎo)入描述文件和本地部署UI項目。

Swagger Editor

類似于markendown編輯器的編輯Swagger描述文件的編輯器，該編輯支持實時預(yù)覽描述文件的更新效果。也提供了在線編輯器和本地部署編輯器兩種方式。

Swagger Inspector

與postman類似，是一個可以對接口進(jìn)行測試的在線版的postman。比在Swagger UI里面做接口請求，會返回更多的信息，也會保存你請求的實際請求參數(shù)等數(shù)據(jù)。

Swagger Hub

集成了上面所有項目的各個功能，你可以以項目和版本為單位，將你的描述文件上傳到Swagger Hub中。在Swagger Hub中可以完成上面項目的所有工作，需要注冊賬號，分免費(fèi)版和收費(fèi)版。

Springfox Swagger

Spring 基于swagger規(guī)范，可以將基于SpringMVC和Spring Boot項目的項目代碼，自動生成JSON格式的描述文件。本身不是屬于Swagger官網(wǎng)提供的，在這里列出來做個說明，方便后面作一個使用的展開。