由于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的依赖
|
1 2 3 4 5 6 7 8 9 10 11 |
<!-- 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来展现，包含注解的方式来确定要显示的接口，当然也可以通过包扫描的方式来确定要显示的包的接口。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
/** * 配置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注解来给参数增加说明。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 |
/** * 系统用户 * * @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为主，其他的基础信息可以参考其他博主内容！
码云地址： https://gitee.com/hrabbit/hrabbit-admin
以上就是本文的全部内容，希望对大家的学习有所帮助，也希望大家多多支持。
原文链接：https://www.jianshu.com/p/8cf56d8e2793
查看更多关于Spring Boot配置Swagger的实现代码的详细内容...