隨著技術(shù)的不斷發(fā)展辞居，現(xiàn)在開發(fā)的模式大部分都是前后端分離，為了跟前端同事溝通方便寨腔，大部分寫后端的朋友都要寫接口文檔速侈，寫接口文檔確實減少了跟前端同事很多不必要的溝通，但是這樣就真的沒有一點缺點了嗎迫卢？
當接口稍微改動就得馬上更新文檔，然后得馬上給前端發(fā)一份冶共，這樣有時候就會造成文檔更新交流不及時乾蛤，前端接收的文檔就會多，不好管理捅僵。
就算文檔更新及時了家卖、前端也整理好了文檔，也不能直接在線測試接口庙楚，通常都需要第三方插件來測試上荡，例如postman。
但是今天我給大家介紹的swagger2就不需要，它不僅能自動生成接口文檔酪捡，還能在線測試接口是否正常叁征！
廢話不多說，咱們直接進入主題逛薇，今天我們就用springboot2來整合swagger2捺疼，直接帶你們應(yīng)用起來。
先說一下我使用的架構(gòu)和版本信息永罚，springboot版本為2.1.6啤呼，swagger的版本為2.8，數(shù)據(jù)底層使用的是mybatis呢袱，mybatis的版本為1.3.2官扣。
第一步：導入依賴
<!-- 導入swagger2的包-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
第二步：配置Swagger類
/**
* 整合swagger2
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurationSupport {
/**
* 設(shè)置一個開關(guān)，生產(chǎn)版本為false羞福，關(guān)閉swagger
*/
@Value("${swagger.ebable}")
private boolean ebable;
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).
enable(ebable).select().apis(RequestHandlerSelectors.basePackage("com.demo.controller")). //掃描包
paths(PathSelectors.any()).build();
//可以設(shè)置為掃描多個包
/**
* com.google.common.base.Predicate<RequestHandler> selector1 = RequestHandlerSelectors.basePackage("設(shè)置你要掃描的包路徑");
* com.google.common.base.Predicate<RequestHandler> selector2 = RequestHandlerSelectors.basePackage("設(shè)置你要掃描的包路徑");
* createRestApi這樣寫即可醇锚。
* @Bean
* public Docket createRestApi(){
* return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).
* enable(ebable).select().
* apis(Predicates.or(selector1,selector2)).
* paths(PathSelectors.any()).build();
* }
*/
}
@SuppressWarnings("deprecation")
public ApiInfo apiInfo(){
return new ApiInfoBuilder().title("接口文檔").
description("服務(wù)端通用接口").version("1.0").build();
}
/**
* 一定要寫這個方法，不然訪問swagger-ui.html頁面會404
* @param registry
*/
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").
addResourceLocations("classpath:/META-INF/resources/").
setCachePeriod(0);
}
}
SwaggerConfig類上有一個ebable屬性坯临，我們可以在yml文件上定義一下焊唬，當我們要上生產(chǎn)環(huán)境時，把這個ebable屬性為false看靠，swagger就關(guān)閉了赶促。
swagger: ##給swagger設(shè)置一個開關(guān)
ebable: true
配置好了，咱們來寫一個controller挟炬。
@RestController
@Api(description = "關(guān)于用戶接口",value = "用戶接口",tags = {"用戶接口"}) //使用@Api來修飾類
public class UserController {
@Autowired
private UserService userService;
@GetMapping("/getUser/{userId}") //使用RestFul風格
//使用@ApiOperation注解來修飾接口
@ApiOperation(value = "通過用戶Id來獲取用戶信息",notes = "RestFul風格鸥滨，需要傳用戶Id")
//使用ApiImplcitParam修飾接口參數(shù)
@ApiImplicitParam(name = "userId",value = "用戶Id",required = true)
public User getUserById(@PathVariable("userId") Integer userId){
return userService.selectById(userId);
}
}
依賴也導入了，配置也配好了谤祖，接口也寫好了婿滓，咱們來啟動一下這個程序吧。
啟動成功后粥喜，直接訪問localhost:8080/swagger-ui.html凸主，就能看到swagger為咱們生成的接口文檔了。
springboot2+swagger2的整合就到此結(jié)束了额湘。但是swagger2還有一些注解沒給大家介紹卿吐，因為swagger2是通過各種注解來生成接口文檔的，下面就給大家介紹介紹swagger2的注解锋华。
@Api：修飾整個類嗡官，描述Controller的作用
@ApiOperation：描述一個類的一個方法，或者說一個接
@ApiParam：單個參數(shù)描述
@ApiModel：用對象來接收參數(shù)
@ApiProperty：用對象接收參數(shù)時毯焕，描述對象的一個字段
@ApiResponse：HTTP響應(yīng)其中1個描述
@ApiResponses：HTTP響應(yīng)整體描述
@ApiIgnore：使用該注解忽略這個API
@ApiError ：發(fā)生錯誤返回的信息
@ApiImplicitParam：一個請求參數(shù)
@ApiImplicitParams：多個請求參數(shù)
整篇文章就到此結(jié)束衍腥，如果大家在整合的過程中還有什么問題可以留言給我，我也把我自己整合的源碼放到github上，大家可以點擊閱讀原文來clone婆咸，下方也留了github的鏈接竹捉，也別忘記給我star哦。
github倉庫鏈接：https://github.com/wuyanzu01/springboot2swagger2
請關(guān)注微信公眾號：請快點喜歡我
