摘要:在项目开发中,往往期望做到前后端分离,也就是后端开发人员往往需要输出大量的服务接口,接口的提供方无论是是java还是php等语言,往往会要花费一定的精力去写接口文档,比如a接口的地址、需要传递参数情况、返回值的json数据格式以及每一个字段说明、当然还要考虑http请求头、请求内容等信息。随着项目的进度快速高速的迭代,后端输出的接口往往会面临修改、修复等问题,那也意味着接口文档也要进行相应的调整。接口文档的维护度以及可读性就大大下降。
既然接口文档需要花费精力去维护,还要适当的进行面对面交流沟通,我们何不想一个办法,第一:可以不用写接口文档;第二:前端与后端沟通接口问题的时候,后端是否可以提供一个url,在这个url中罗列出所有可以调用的服务接口,并在每个服务接口中罗列出参数的说明,返回值的说明,第三:后端接口如果能模拟调用就所有问题都解决了。本文我们重点讲解一下sringboot中集成swagger2框架。
1.1. 添加swagger2依赖
在项目的pom.xml文件中增加如下的依赖。
1
2
3
4
5
6
7
8
9
10
|
<dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger2</artifactid> <version> 2.7 . 0 </version> </dependency> <dependency> <groupid>io.springfox</groupid> <artifactid>springfox-swagger-ui</artifactid> <version> 2.7 . 0 </version> </dependency> |
首先,我们需要建立一个启动类,代码如下:
1
2
3
4
5
6
|
@springbootapplication public class application { public static void main(string[] args) { springapplication.run(application. class , args); } } |
然后在上述类的同级目录中新建swagger2的配置类如下所示:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
|
@configuration @enableswagger2 public class swagger2 { @bean public docket createrestapi() { return new docket(documentationtype.swagger_2) .apiinfo(apiinfo()) .select() .apis(requesthandlerselectors.basepackage( "com.shareniu.web" )) .paths(pathselectors.any()) .build(); } private apiinfo apiinfo() { return new apiinfobuilder() .title( "跟着分享牛学习springboot源码分析系列课程" ) .description( "更多spring boot相关文章请关注分享牛的博客" ) .termsofserviceurl( "http://www.shareniu.com/" ) .contact( "牛牛" ) .license( "copyright 2017-2018 分享牛" ) .version( "1.0" ) .build(); } } |
@configuration制定了spring要加载这个类,@enableswagger2注解要开启swagger功能。
上述中的apiinfo最终都会展现在前端,我们使用了扫描包的方式配置配置,也就是requesthandlerselectors.basepackage。在这个包以及子包中的控制器最终都是生成api文档。(除了被@apiignore注解指定的请求)。
1.2. 新增文档说明
上述的类声明之后,我们其实就可以直接调用了,但是为了增加文档的可读性,我们还是需要在接口中增加一些说明,我们先写一个控制器如下所示:
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
|
@restcontroller @requestmapping (value= "/users" ) public class usercontroller { static map< long , user> users = collections.synchronizedmap( new hashmap< long , user>()); static { user user = new user(); user.setage( 18 ); user.setid(1l); user.setname( "aa" ); users.put(1l, user); } @apioperation (value= "获取所有用户列表" , notes= "" ) @requestmapping (value={ "" }, method=requestmethod.get) public list<user> getuserlist() { list<user> r = new arraylist<user>(users.values()); return r; } @apioperation (value= "创建新的用户" , notes= "根据user对象创建用户" ) @apiimplicitparam (name = "user" , value = "用户详细实体user" , required = true , datatype = "user" ) @requestmapping (value= "" , method=requestmethod.post) public string postuser( @requestbody user user) { users.put(user.getid(), user); return "success" ; } @apioperation (value= "获取用户详细信息" , notes= "根据url的id来获取用户详细信息" ) @apiimplicitparam (name = "id" , value = "用户id" , required = true , datatype = "long" ) @requestmapping (value= "/{id}" , method=requestmethod.get) public user getuser( @pathvariable long id) { return users.get(id); } @apioperation (value= "更新用户详细信息" , notes= "根据url的id来指定更新对象" ) @apiimplicitparams ({ @apiimplicitparam (name = "id" , value = "用户id" , required = true , datatype = "long" ), @apiimplicitparam (name = "user" , value = "用户详细实体user" , required = true , datatype = "user" ) }) @requestmapping (value= "/{id}" , method=requestmethod.put) public string putuser( @pathvariable long id, @requestbody user user) { user u = users.get(id); u.setname(user.getname()); u.setage(user.getage()); users.put(id, u); return "success" ; } @apioperation (value= "删除已存在的用户" , notes= "根据url的id来指定删除对象" ) @apiimplicitparam (name = "id" , value = "用户id" , required = true , datatype = "long" ) @requestmapping (value= "/{id}" , method=requestmethod.delete) public string deleteuser( @pathvariable long id) { users.remove(id); return "success" ; } } |
@apioperation:用来描述该接口的作用。可以通过该注解说明接口的职责、返回头信息、方法的请求方式("get", "head", "post", "put", "delete", "options" and "patch")、协议( http, https, ws, wss)、http状态码。
@apiimplicitparam:用来给参数增加说明。可以设置参数的名称、是否是必填项、参数的描述信息、是否只读等。
上述代码提交之后,启动springboot,访问,如下图所示:
上图分为两个部分,上部分是通过swagger2类配置出来的,下半部分是usercontroller类中的接口文档。
这里我们以/user为例进行说明:
点击/user如下图所示:
上图黄色的地方表示,该接口返回的样例数据。也就是user的数据结构。response content type:接口返回的头信息。点击try it out。如下所示:
该接口返回的baody、code码、响应头已经成功返回了。
总结
以上所述是小编给大家介绍的springboot中集成swagger2框架的方法,希望对大家有所帮助,如果大家有任何疑问请给我留言,小编会及时回复大家的。在此也非常感谢大家对服务器之家网站的支持!
原文链接:http://blog.csdn.net/qq_30739519/article/details/78779317