Spring Boot配置Swagger的實(shí)現(xiàn)代碼
由于Spring Boot能夠快速開發(fā)、便捷部署等特性,相信有很大一部分Spring Boot的用戶會用來構(gòu)建RESTful API。而我們構(gòu)建RESTful API的目的通常都是由于多終端的原因,這些終端會共用很多底層業(yè)務(wù)邏輯,因此我們會抽象出這樣一層來同時服務(wù)于多個移動端或者Web前端。
Swagger Inspector:測試API和生成OpenAPI的開發(fā)工具。Swagger Inspector的建立是為了解決開發(fā)者的三個主要目標(biāo)。
- 執(zhí)行簡單的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>
創(chuàng)建Swagger2配置類
在HrabbitAdminApplication.java子包下創(chuàng)建Swagger2的配置類Swagger2。
通過@Configuration注解,讓Spring來加載該類配置。再通過@EnableSwagger2注解來啟用Swagger2。
再通過createRestApi函數(shù)創(chuàng)建Docket的Bean之后,apiInfo()用來創(chuàng)建該Api的基本信息(這些基本信息會展現(xiàn)在文檔頁面中)。select()函數(shù)返回一個ApiSelectorBuilder實(shí)例用來控制哪些接口暴露給Swagger來展現(xiàn),包含注解的方式來確定要顯示的接口,當(dāng)然也可以通過包掃描的方式來確定要顯示的包的接口。
/** * 配置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(); } }
添加文檔內(nèi)容
我們通過@Api說明Controller,@ApiOperation注解來給API增加說明、通過@ApiImplicitParams、@ApiImplicitParam注解來給參數(shù)增加說明。
/** * 系統(tǒng)用戶 * * @Auther: hrabbit * @Date: 2018-12-17 6:21 PM * @Description: */ @Controller @RequestMapping("user") @Api(value = "系統(tǒng)用戶") public class SysUserController { @Autowired private SysUserService sysUserService; /** * 根據(jù)id獲取用戶信息 * * @return */ @RequestMapping("/",method = RequestMethod.GET) @ResponseBody @ApiOperation(value = "進(jìn)入到主頁") public Object index() { return sysUserService.selectById(1L); } /** * 創(chuàng)建用戶信息 * * @param user * @return */ @ApiOperation(value = "創(chuàng)建用戶", notes = "根據(jù)SysUser對象創(chuàng)建用戶") @ApiImplicitParam(name = "user", value = "用戶詳細(xì)實(shí)體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 = "更新用戶詳細(xì)信息", notes = "根據(jù)id更新系統(tǒng)用戶") @ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long"), @ApiImplicitParam(name = "user", value = "用戶詳細(xì)實(shí)體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的頁面。我們可以再點(diǎn)開具體的API請求,以POST類型的/user請求為例,可找到上述代碼中我們配置的Notes信息以及參數(shù)user的描述信息,如下圖所示。
API文檔訪問與調(diào)試
在上圖請求的頁面中,我們看到user的Value是個輸入框?是的,Swagger除了查看接口功能外,還提供了調(diào)試測試功能,我們可以點(diǎn)擊上圖中右側(cè)的Model Schema(黃色區(qū)域:它指明了User的數(shù)據(jù)結(jié)構(gòu)),此時Value中就有了user對象的模板,我們只需要稍適修改,點(diǎn)擊下方“Try it out!”按鈕,即可完成了一次請求調(diào)用!
本篇文章,一些文字內(nèi)容借鑒了程序猿DD的Swagger內(nèi)容,該系列文章內(nèi)容主要以如何搭建一個完整的后臺Spirng Boot Cli為主,其他的基礎(chǔ)信息可以參考其他博主內(nèi)容!
碼云地址:https://gitee.com/hrabbit/hrabbit-admin
以上就是本文的全部內(nèi)容,希望對大家的學(xué)習(xí)有所幫助,也希望大家多多支持腳本之家。
相關(guān)文章
Java中Scanner類與BufferReader類的不同點(diǎn)(非常詳細(xì))
這篇文章主要介紹了Java中Scanner類與BufferReader類的不同點(diǎn)(非常詳細(xì))的相關(guān)資料,需要的朋友可以參考下2016-08-08詳解Mybatis多參數(shù)傳遞入?yún)⑺姆N處理方式
這篇文章主要介紹了詳解Mybatis多參數(shù)傳遞入?yún)⑺姆N處理方式,文中通過示例代碼介紹的非常詳細(xì),對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值,需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2021-04-04