前言：
作爲標標準準的後臺開發攻城獅，在於前端交互給其提供接口的時候，是不是要給其準備接口文檔？是不是在和他聯調之前首先要自測通過呢？是不是自測之前要寫接口調用（比如postman）呢？作爲一個負責滴、追求向上滴工程師，那這些肯定是要做的。事情都要做，可做事的方式不同，結果和效率也不同，那麼下面和大家分享一下springboot項目中提供的接口如何方便快捷提供一種自測，甚至是直接給接口測試人員測試的方式，那就是整合進去seagger2.用了還想用的第三方插件吧，
申明：
我不喜歡文章很複雜，追求簡而美觀的實用性，但是爲了需要的夥伴能夠直接一步到位，絕對可用，所以直接粘貼的核心代碼，方便你們複製過去，因此給文章增加了看起來不太友好的複雜度。
開發環境：
1、添加依賴
這裏默認我們已使用的maven項目，否則的話請自行下載依賴相關的java包也一樣，項目引入以下依賴：
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency><!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、添加配置類
package cn.seally.community.config;
import static com.google.common.base.Predicates.or;
import static springfox.documentation.builders.PathSelectors.regex;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;import com.google.common.base.Predicate;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;/**
* @Description swagger在線接口插件配置類
* @Date 2019年8月31日
* @author seallydeng
*/
@Configuration
@EnableSwagger2 //開啓在線接口文檔
public class SwaggerConfig {
/**
* @Description
* @Date 2019年8月31日
* @author seallydeng
* @return
*/
@Bean
public Docket controllerApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(new ApiInfoBuilder()
.title("標題：Seally Web 接口文檔")//標題
.description("本系統接口主要包括xxx、yyy等功能模塊")//描述
.contact(new Contact("dningcheng", "http://www.xxx.com/web", "[email protected]"))
.version("1.0.0")//版本號
.build())
.select()
.apis(RequestHandlerSelectors.basePackage("cn.seally.community.controller"))//配置掃描的控制器類包
.paths(paths())//配置符合指定規則的路徑接口才生成在線接口，用於定製那些接口在ui中展示
.build();
}
@SuppressWarnings("unchecked")
private Predicate<String> paths() {
return or(regex("/user/api/.*?"));
}
}
3、控制器以註解方式增加接口描述信息
package cn.seally.community.controller;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;import cn.seally.community.common.ApiResponse;
import cn.seally.community.model.base.SystemUser;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;/**
* @Description 用於演示swagger在線接口文檔的控制器
* @Date 2019年8月31日
* @author seallydeng
*/
@Api(tags={"系統首頁熱點圖相關接口"}) //標註在類上：用以備註接口組名稱
@RestController
@RequestMapping("/demo")
public class DemoController {
@ApiOperation(value="獲取用戶信息",notes="username是唯一屬性，單個用戶可直接通過username獲取") //標註在方法：用以備註接口描述
@GetMapping(value="/user/query")
public ApiResponse<String> getUserInfo(String username){
return ApiResponse.success("獲取信息通過");
}
@PostMapping(value="/user/save",produces="application/json")
public ApiResponse<String> saveUserInfo(@RequestBody SystemUser user){
return ApiResponse.success("保存用戶信息成功");
}
@PutMapping(value="/user/update",produces="application/json")
public ApiResponse<String> updateUserInfo(@RequestBody SystemUser user){
return ApiResponse.success("修改用戶信息成功");
}
@DeleteMapping(value="/user/delete/{username}",produces="application/json")
public ApiResponse<String> deleteUserInfo(@PathVariable("username") String username){
return ApiResponse.success("刪除用戶信息成功");
}
}
4、啓動項目，進行訪問
在瀏覽器輸入訪問路徑即可訪問，通常如果項目沒有配置路徑則直接使用：http://ip:port/swagger-ui.html 即可訪問，如果springboot配置了項目路徑如:
那麼訪問的路徑名則爲：http://ip:port/seally-community-web/swagger-ui.html
如果項目正常，則可看到如下界面：
讓我們點開一個方法看下：
界面太大所以只截取部分，這裏我們只需要輸入請求參數，點擊執行，就可以看奧執行結果如：
同時右邊還有下載按鈕可以直接下載到一個json格式的返回值。
通常各種方法在swagger的接口界面都會爲我們對應生成參數，只需要填寫值就可直接執行請求，以下是post請求，以application/json方式發起請求的示例：
總結：
swagger2是不是很好用了，上面只演示了覺得用得上的註解，當然它還有一系列的註解幫助我們對接口和入參進行詳細說明比如：
@ApiImplicitParams：用在請求的方法上，表示一組參數說明
@ApiImplicitParam：用在@ApiImplicitParams註解中，代表某一個具體參數，用於單個參數的各個信息說明
@ApiResponses：用在請求的方法上，表示一組響應
@ApiResponse：用在@ApiResponses中，表示響應的某個具體參數，用於對具體參數的各個方面進行說明
@ApiModel：用於響應類上，表示一個返回響應數據的信息
@ApiModelProperty：和@ApiModel搭配使用，用在響應類的屬性上，描述響應類的屬性信息
這些註解，可根據需要使用，通常只要參數定義的好，有具體的語義，我覺得不需要這麼詳細的備註，額外增加寫註解的工作量。
怎麼樣，是不是很簡單呢，有需要的小夥伴兒們，趕快試試吧，如果覺得好用，不妨幫我點個贊，鼓勵鼓勵我在分享的路上，永不止步哦...!