服务器之家

服务器之家 > 正文

Spring Boot配置Swagger的实现代码

时间:2021-06-24 09:56     来源/作者:hrabbits

由于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的描述信息,如下图所示。

Spring Boot配置Swagger的实现代码

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

标签:

相关文章

热门资讯

2020微信伤感网名听哭了 让对方看到心疼的伤感网名大全
2020微信伤感网名听哭了 让对方看到心疼的伤感网名大全 2019-12-26
yue是什么意思 网络流行语yue了是什么梗
yue是什么意思 网络流行语yue了是什么梗 2020-10-11
背刺什么意思 网络词语背刺是什么梗
背刺什么意思 网络词语背刺是什么梗 2020-05-22
苹果12mini价格表官网报价 iPhone12mini全版本价格汇总
苹果12mini价格表官网报价 iPhone12mini全版本价格汇总 2020-11-13
2021德云社封箱演出完整版 2021年德云社封箱演出在线看
2021德云社封箱演出完整版 2021年德云社封箱演出在线看 2021-03-15
返回顶部