springboot整合swagger，前后端接口規范

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

 

1、創建一個springboot項目

2、添加swagger2的maven依賴

3、創建swagger的配置類，在appliacation的同級目錄下創建swagger類

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

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

4、接下來就可以通過使用注解，在接口類中添加文檔內容

@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 用在實體對象的字段上 用於描述字段含義

 

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

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

7、當然你還可以點擊下面的 try it out來檢驗該接口是否可以正常訪問

總結：

這只是簡單總結了springboot整合swagger的簡單用法，如果以后工作學習中碰到了更深層次的東西也會及時補充的。