springboot整合swagger，先後端接口規範

　　在咱們的實際開發中，費事寫完一個接口以後，還要維護該接口的接口文檔，接口少還好說，當接口數量不少，維護接口文檔也會是一個很繁重的任務。還有一點就是在咱們修改完一個接口後，咱們常常忘記把修改的內容添加到接口文檔以內，或者咱們添加了但前端同窗沒有及時注意到，因此這就會形成先後端的接口信息不一樣步，影響開發進度以及質量。這兩天我簡單總結了一下swagger2和springboot的整合。它既能夠減小咱們建立文檔的工做量，同時說明內容又整合入實現代碼中，讓維護文檔和修改代碼整合爲一體，可讓咱們在修改代碼邏輯的同時方便的修改文檔說明。另外Swagger2也提供了強大的頁面測試功能來調試每一個RESTful API。

 

一、建立一個springboot項目

二、添加swagger2的maven依賴

三、建立swagger的配置類，在appliacation的同級目錄下建立swagger類

經過@configuration註解，讓spring來加載此類的配置。basePackage內的包名也就是，接口存在的包，swagger會掃描並顯示其下的接口

*注意，應該在springboot的Application類下添加@EnableSwagger2註解來啓用swagger2

四、接下來就能夠經過使用註解，在接口類中添加文檔內容

@Api  用於controller類上   對類的功能進行描述

@ApiOperation  用在controller方法上  對類的方法進行描述

@ApiImplicitParam 用在Controller方法上 對方法須要傳進來的參數進行描述

　　paramType 有path以地址形式提交數據、query直接跟參數完成自動映射賦值（get方法使用）、body以流的形式提交僅支持POST（@requestBody）、header參數在request headers裏面提交、form以form表單形式提交僅支持POST，dataType若是是自定義的實體對象，須要在請求參數時加上@requestBody註解

@ApiImplicitParams  用在controller方法上，若是一個方法有多個請求參數，須要有該註解將@ApiImplicitParam包在裏面

@ApiResponse 用在controller方法上，定義返回的錯誤號，以及其表達的含義

@ApiResponses 用在controller方法上， 當須要定義多個@ApiResponse時，須要用到該註解將它們包在裏面

@ApiModel 用在返回對象類上   描述返回對象的意義

@ApiModelProperty 用在實體對象的字段上 用於描述字段含義

 

 五、接下來訪問  http://localhost:8080/swagger-ui.html#/ 能夠看到生成的文檔頁

六、點擊查看相應的方法對應的生成接口文檔

七、固然你還能夠點擊下面的 try it out來檢驗該接口是否能夠正常訪問

總結：

這只是簡單總結了springboot整合swagger的簡單用法，若是之後工做學習中碰到了更深層次的東西也會及時補充的。