隨著技術(shù)的不斷發(fā)展，現(xiàn)在開發(fā)的模式大部分都是前后端分離，為了跟前端同事溝通方便，大部分寫后端的朋友都要寫接口文檔，寫接口文檔確實(shí)減少了跟前端同事很多不必要的溝通，但是這樣就真的沒有一點(diǎn)缺點(diǎn)了嗎？
當(dāng)接口稍微改動(dòng)就得馬上更新文檔，然后得馬上給前端發(fā)一份，這樣有時(shí)候就會(huì)造成文檔更新交流不及時(shí)，前端接收的文檔就會(huì)多，不好管理。
就算文檔更新及時(shí)了、前端也整理好了文檔，也不能直接在線測(cè)試接口，通常都需要第三方插件來測(cè)試，例如postman。
但是今天我給大家介紹的swagger2就不需要，它不僅能自動(dòng)生成接口文檔，還能在線測(cè)試接口是否正常！
廢話不多說，咱們直接進(jìn)入主題，今天我們就用springboot2來整合swagger2，直接帶你們應(yīng)用起來。
先說一下我使用的架構(gòu)和版本信息，springboot版本為2.1.6，swagger的版本為2.8，數(shù)據(jù)底層使用的是mybatis，mybatis的版本為1.3.2。
第一步：導(dǎo)入依賴
<!-- 導(dǎo)入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è)置一個(gè)開關(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è)置為掃描多個(gè)包
/**
* 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();
}
/**
* 一定要寫這個(gè)方法，不然訪問swagger-ui.html頁面會(huì)404
* @param registry
*/
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**").
addResourceLocations("classpath:/META-INF/resources/").
setCachePeriod(0);
}
}
SwaggerConfig類上有一個(gè)ebable屬性，我們可以在yml文件上定義一下，當(dāng)我們要上生產(chǎn)環(huán)境時(shí)，把這個(gè)ebable屬性為false，swagger就關(guān)閉了。
swagger: ##給swagger設(shè)置一個(gè)開關(guān)
ebable: true
配置好了，咱們來寫一個(gè)controller。
@RestController
@Api(description = "關(guān)于用戶接口",value = "用戶接口",tags = {"用戶接口"}) //使用@Api來修飾類
public class UserController {
@Autowired
private UserService userService;
@GetMapping("/getUser/{userId}") //使用RestFul風(fēng)格
//使用@ApiOperation注解來修飾接口
@ApiOperation(value = "通過用戶Id來獲取用戶信息",notes = "RestFul風(fēng)格，需要傳用戶Id")
//使用ApiImplcitParam修飾接口參數(shù)
@ApiImplicitParam(name = "userId",value = "用戶Id",required = true)
public User getUserById(@PathVariable("userId") Integer userId){
return userService.selectById(userId);
}
}
依賴也導(dǎo)入了，配置也配好了，接口也寫好了，咱們來啟動(dòng)一下這個(gè)程序吧。
啟動(dòng)成功后，直接訪問localhost:8080/swagger-ui.html，就能看到swagger為咱們生成的接口文檔了。
springboot2+swagger2的整合就到此結(jié)束了。但是swagger2還有一些注解沒給大家介紹，因?yàn)閟wagger2是通過各種注解來生成接口文檔的，下面就給大家介紹介紹swagger2的注解。
@Api：修飾整個(gè)類，描述Controller的作用
@ApiOperation：描述一個(gè)類的一個(gè)方法，或者說一個(gè)接
@ApiParam：?jiǎn)蝹€(gè)參數(shù)描述
@ApiModel：用對(duì)象來接收參數(shù)
@ApiProperty：用對(duì)象接收參數(shù)時(shí)，描述對(duì)象的一個(gè)字段
@ApiResponse：HTTP響應(yīng)其中1個(gè)描述
@ApiResponses：HTTP響應(yīng)整體描述
@ApiIgnore：使用該注解忽略這個(gè)API
@ApiError ：發(fā)生錯(cuò)誤返回的信息
@ApiImplicitParam：一個(gè)請(qǐng)求參數(shù)
@ApiImplicitParams：多個(gè)請(qǐng)求參數(shù)
整篇文章就到此結(jié)束，如果大家在整合的過程中還有什么問題可以留言給我，我也把我自己整合的源碼放到github上，大家可以點(diǎn)擊閱讀原文來clone，下方也留了github的鏈接，也別忘記給我star哦。
github倉庫鏈接：https://github.com/wuyanzu01/springboot2swagger2
請(qǐng)關(guān)注微信公眾號(hào)：請(qǐng)快點(diǎn)喜歡我
