超簡單的springboot+swagger2實現在線接口調試

前言：

????作為標標準準的后臺開發攻城獅，在于前端交互給其提供接口的時候，是不是要給其準備接口文檔？是不是在和他聯調之前首先要自測通過呢？是不是自測之前要寫接口調用（比如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", "dningcheng@163.com"))
??????????????????????? .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搭配使用，用在響應類的屬性上，描述響應類的屬性信息

這些注解，可根據需要使用，通常只要參數定義的好，有具體的語義，我覺得不需要這么詳細的備注，額外增加寫注解的工作量。

怎么樣，是不是很簡單呢，有需要的小伙伴兒們，趕快試試吧，如果覺得好用，不妨幫我點個贊，鼓勵鼓勵我在分享的路上，永不止步哦...!