Swagger
隨著前后端分離架構(gòu)和微服務(wù)架構(gòu)的流行油狂，我們使用Spring Boot來構(gòu)建RESTful API項(xiàng)目的場景越來越多，在多人協(xié)作的團(tuán)隊(duì)中企锌，前后端的溝通成本往往比較大榆浓。在這樣的背景下，Swagger出現(xiàn)了(當(dāng)然還有其他的就不一一例舉了)撕攒。
使用 Swagger 集成文檔具有以下幾個(gè)優(yōu)勢：
- 功能豐富 ：支持多種注解陡鹃，自動(dòng)生成接口文檔界面，支持在界面測試API接口功能
- 及時(shí)更新 ：開發(fā)過程中花一點(diǎn)寫注釋的時(shí)間抖坪，就可以及時(shí)的更新API文檔萍鲸，省心省力
- 整合簡單 ：通過添加pom依賴和簡單配置，內(nèi)嵌于應(yīng)用中就可同時(shí)發(fā)布API接口文檔界面擦俐，不需要部署獨(dú)立服務(wù)
開始整合Swagger2
在上一篇的項(xiàng)目基礎(chǔ)上猿推，我們來使用一下Swagger。
- 首先捌肴，我們需要在pom.xml中添加依賴,如下:
<!-- swagger蹬叭、swagger-ui 依賴 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
- 接下來我們來編寫一個(gè)SwaggerConfig配置類
新建一個(gè)包:com.zhlab.demo.config,創(chuàng)建SwaggerConfig類
SwaggerConfig.java
package com.zhlab.demo.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @ClassName SwaggerConfig
* @Description //SwaggerConfig配置類
* @Author singleZhang
* @Email 405780096@qq.com
* @Date 2020/10/17 0017 上午 11:11
**/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket creatRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(this.apiInfo())
.select()
//掃描指定路徑
.apis(RequestHandlerSelectors.basePackage("com.zhlab.demo.controller"))
// 掃描所有有注解的api，用這種方式更靈活
//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 掃描所有
// .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("zhLab Demo Api Doc")
.description("api document of zhLab Demo")
.version("1.0.1")
.build();
}
}
※說明:
- 在類上状知，添加 @EnableSwagger2 注解秽五， 標(biāo)記項(xiàng)目啟用 Swagger API 接口文檔。
- 通過 createRestApi() 方法饥悴，創(chuàng)建 Swagger Docket Bean
- 更多的配置可以在Docket.java坦喘、ApiInfo.java兩個(gè)類的源碼中查看
- 修改上一篇中的HelloController控制器
package com.zhlab.demo.controller;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
/**
* @ClassName HelloController
* @Description //第一個(gè)Springboot接口
* @Author singleZhang
* @Email 405780096@qq.com
* @Date 2020/10/16 0016 上午 10:55
**/
@RestController
@RequestMapping("/system/user")
public class HelloController {
/* 方法注解 */
@ApiOperation(value = "方法名:打招呼", notes = "打招呼方法的測試")
@GetMapping("/hello")
public String sayHello(/* 參數(shù)注解 */ @ApiParam(value = "參數(shù):名字" , required=true ) @RequestParam String name){
return "hi"+name+" ,I can say hello";
}
}
啟動(dòng)項(xiàng)目,在瀏覽器輸入http://localhost:8080/swagger-ui.html顯示下圖:
執(zhí)行一下盲再，測試一下接口:
常用注解說明
swagger 通過注解接口生成文檔，包括接口名瓣铣，請求方法答朋，參數(shù)，返回信息等棠笑。
@Api: 修飾整個(gè)類梦碗，用于controller類上
@ApiOperation: 描述一個(gè)接口，用戶controller方法上
@ApiParam: 單個(gè)參數(shù)描述
@ApiModel: 用來對象接收參數(shù),即返回對象
@ApiModelProperty: 對象接收參數(shù)時(shí)蓖救，描述對象的字段
@ApiResponse: Http響應(yīng)其中的描述洪规，在ApiResonse中
@ApiResponses: Http響應(yīng)所有的描述，用在
@ApiIgnore: 忽略這個(gè)API
@ApiError: 發(fā)生錯(cuò)誤的返回信息
@ApiImplicitParam: 一個(gè)請求參數(shù)
@ApiImplicitParam: 多個(gè)請求參數(shù)
總結(jié)
以上就是對Swagger的初步體驗(yàn),前后端分離api文檔是節(jié)省溝通成本的重要工具循捺，用好它斩例，你肯定會如虎添翼，以后還會推薦YAPI等工具从橘。
