由於Spring Boot能夠快速開發、便捷部署等特性,相信有很大一部分Spring Boot的用戶會用來構建RESTful API。而我們構建RESTful API的目的通常都是由於多終端的原因,這些終端會共用很多底層業務邏輯,因此我們會抽象出這樣一層來同時服務於多個移動端或者Web前端。
Swagger Inspector:測試API和生成OpenAPI的開發工具。Swagger Inspector的建立是爲了解決開發者的三個主要目標。
- 執行簡單的API測試
- 生成OpenAPI文檔
- 探索新的API功能
下面來具體介紹,如果在Spring Boot
中使用Swagger2
。
添加Swagger2依賴
在pom.xml
中加入Swagger2的依賴
<!-- Swagger API-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
創建Swagger2配置類
在HrabbitAdminApplication.java子包下創建Swagger2的配置類Swagger2。
通過@Configuration
註解,讓Spring
來加載該類配置。再通過@EnableSwagger2
註解來啓用Swagger2
。
再通過createRestApi
函數創建Docket
的Bean
之後,apiInfo()
用來創建該Api
的基本信息(這些基本信息會展現在文檔頁面中)。select()函數返回一個ApiSelectorBuilder
實例用來控制哪些接口暴露給Swagger
來展現,包含註解的方式來確定要顯示的接口,當然也可以通過包掃描的方式來確定要顯示的包的接口。
/**
* 配置Swagger
*
* @Auther: hrabbit
* @Date: 2018-12-17 6:43 PM
* @Description:
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //這裏採用包含註解的方式來確定要顯示的接口
//.apis(RequestHandlerSelectors.basePackage("com.hrabbit.admin.modual.system.controller")) //這裏採用包掃描的方式來確定要顯示的接口
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Hrabbit-Admin Doc")
.description("Guns Api文檔")
.termsOfServiceUrl("https://gitee.com/hrabbit/hrabbit-admin")
.contact("hrabbit")
.version("1.0")
.build();
}
}
添加文檔內容
我們通過@Api
說明Controller,@ApiOperation
註解來給API增加說明、通過@ApiImplicitParams
、@ApiImplicitParam
註解來給參數增加說明。
/**
* 系統用戶
*
* @Auther: hrabbit
* @Date: 2018-12-17 6:21 PM
* @Description:
*/
@Controller
@RequestMapping("user")
@Api(value = "系統用戶")
public class SysUserController {
@Autowired
private SysUserService sysUserService;
/**
* 根據id獲取用戶信息
*
* @return
*/
@RequestMapping("/",method = RequestMethod.GET)
@ResponseBody
@ApiOperation(value = "進入到主頁")
public Object index() {
return sysUserService.selectById(1L);
}
/**
* 創建用戶信息
*
* @param user
* @return
*/
@ApiOperation(value = "創建用戶", notes = "根據SysUser對象創建用戶")
@ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "SysUser")
@RequestMapping(value = "", method = RequestMethod.POST)
public String postUser(@RequestBody SysUser user) {
return "success";
}
/**
* 修改用戶信息
*
* @param id
* @param user
* @return
*/
@ApiOperation(value = "更新用戶詳細信息", notes = "根據id更新系統用戶")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long"),
@ApiImplicitParam(name = "user", value = "用戶詳細實體sysUser", required = true, dataType = "SysUser")
})
@RequestMapping(value = "/{id}", method = RequestMethod.PUT)
public String putUser(@PathVariable Long id, @RequestBody SysUser user) {
return "success";
}
}
完成上述代碼添加上,啓動Spring Boot程序,訪問:http://localhost:8080/swagger-ui.html
。就能看到前文所展示的RESTful API的頁面。我們可以再點開具體的API請求,以POST類型的/user請求爲例,可找到上述代碼中我們配置的Notes信息以及參數user的描述信息,如下圖所示。
API文檔訪問與調試
在上圖請求的頁面中,我們看到user
的Value
是個輸入框?是的,Swagger
除了查看接口功能外,還提供了調試測試功能,我們可以點擊上圖中右側的Model Schema
(黃色區域:它指明瞭User
的數據結構),此時Value
中就有了user
對象的模板,我們只需要稍適修改,點擊下方“Try it out!”
按鈕,即可完成了一次請求調用!
本篇文章,一些文字內容借鑑了程序猿DD
的Swagger
內容,該系列文章內容主要以如何搭建一個完整的後臺Spirng Boot Cli
爲主,其他的基礎信息可以參考其他博主內容!