服务器之家

服务器之家 > 正文

SpringBoot集成Swagger2生成接口文档的方法示例

时间:2021-06-23 14:10     来源/作者:名字想好没

我们提供restful接口的时候,api文档是尤为的重要,它承载着对接口的定义,描述等。它还是和api消费方沟通的重要工具。在实际情况中由于接口和文档存放的位置不同,我们很难及时的去维护文档。个人在实际的工作中就遇到过很多接口更新了很久,但是文档却还是老版本的情况,其实在这个时候这份文档就已经失去了它存在的意义。而 swagger 是目前我见过的最好的api文档生成工具,使用起来也很方便,还可以直接调试我们的api。我们今天就来看下 swagger2springboot 的结合。

准备工作

一个springboot项目,可以直接去官网生成一个demo 

一个用户类。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
package cn.itweknow.springbootswagger.model;
 
import java.io.serializable;
 
/**
 * @author ganchaoyang
 * @date 2018/12/19 10:29
 * @description
 */
public class user implements serializable {
 
 private integer id;
 
 private string name;
 
 private string password;
 
 private string email;
}

项目依赖

web service肯定是一个web项目,所以我们这里依赖了 spring-boot-starter-web 包,其他两个包就是和 swagger 相关的包了。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<dependency>
 <groupid>org.springframework.boot</groupid>
 <artifactid>spring-boot-starter-web</artifactid>
</dependency>
 
<dependency>
 <groupid>io.springfox</groupid>
 <artifactid>springfox-swagger2</artifactid>
 <version>2.9.2</version>
</dependency>
 
<dependency>
 <groupid>io.springfox</groupid>
 <artifactid>springfox-swagger-ui</artifactid>
 <version>2.9.2</version>
</dependency>

swagger配置

springfox docket实例为swagger配置提供了便捷的配置方法以及合理的默认配置。我们将通过创建一个docket实例来对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
34
35
36
37
38
@configuration
@enableswagger2
public class swaggerconfig extends webmvcconfigurationsupport {
 
 @bean
 public docket productapi() {
  return new docket(documentationtype.swagger_2).select()
    // 扫描的包路径
    .apis(requesthandlerselectors.basepackage("cn.itweknow.springbootswagger.controller"))
    // 定义要生成文档的api的url路径规则
    .paths(pathselectors.any())
    .build()
    // 设置swagger-ui.html页面上的一些元素信息。
    .apiinfo(metadata());
 }
 
 private apiinfo metadata() {
  return new apiinfobuilder()
    // 标题
    .title("springboot集成swagger2")
    // 描述
    .description("这是一篇博客演示")
    // 文档版本
    .version("1.0.0")
    .license("apache license version 2.0")
    .licenseurl("https://www.apache.org/licenses/license-2.0")
    .build();
 }
 
 @override
 protected void addresourcehandlers(resourcehandlerregistry registry) {
  registry.addresourcehandler("swagger-ui.html")
    .addresourcelocations("classpath:/meta-inf/resources/");
 
  registry.addresourcehandler("/webjars/**")
    .addresourcelocations("classpath:/meta-inf/resources/webjars/");
 }
}

上述代码中的addresourcehandlers方法添加了两个资源处理程序,这段代码的主要作用是对swagger ui的支持。

api文档

好了,到这一步,我们已经在一个springboot项目中配置好了swagger。现在,我们就来看一下如何去使用他。首先我们定义了一个 controller 并提供了两个接口:

  • 通过用户id获取用户
  • 用户登录
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
@restcontroller
@requestmapping("/user")
@api(description = "用户相关接口")
public class usercontroller {
 
 /**
  * 通过id查询用户
  * @return
  */
 @requestmapping(value = "/get", method = requestmethod.get)
 @apioperation("根据id获取用户")
 public user getuserbyid(@apiparam(value = "用户id") integer id) {
  return new user();
 }
 
 @requestmapping(value = "/login", method = requestmethod.post)
 @apioperation("用户登录")
 public user login(@requestbody user user) {
  return new user();
 }
}

相信大家都注意到了,这个 controller 里面多了很多新的注解,比如说 @api , @apioperation 等,下面我们就来一一解释一下。

  • @api,这个注解是用在controller类上面的,可以对controller做必要的说明。
  • @apioperation,作用在具体的方法上,其实就是对一个具体的api的描述。
  • @apiparam,对api参数的描述。

到这里,其实我们的swagger就已经可以有效果了,让我们将项目运行起来先看看效果。访问 http://localhost:8080/swagger-ui.html 即可。

SpringBoot集成Swagger2生成接口文档的方法示例

model

在上面的图中可以看到在页面的下方有一个models的标签,那么这个是啥呢。其实这个就是我们api中出现的一些对象的文档,我们也可以通过注解来对这些对象中的字段做一些说明,以方便使用者理解。以文章开头提到的 user 类来做一个说明。

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@apimodel("用户实体")
public class user implements serializable {
 
 @apimodelproperty(value = "用户id")
 private integer id;
 
 @apimodelproperty(value = "用户名称", required = true)
 private string name;
 
 @apimodelproperty(value = "密码", required = true)
 private string password;
 
 @apimodelproperty(value = "用户邮箱")
 private string email;
}

我们来看一下 user 类在swagger上是如何展示的:

SpringBoot集成Swagger2生成接口文档的方法示例

有一个细节,那就是required = true的字段上面被红星修饰,代表了必填项。

api测试

swagger-ui.html 页面上我们可以直接测试api,如下图所示,点击 try it out ,然后填写参数,并点击 execute 即可进行调用。

SpringBoot集成Swagger2生成接口文档的方法示例

好了,对于swagger的介绍就到这里了,最后奉上本文的源码地址,请戳这里

以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持服务器之家。

原文链接:https://www.jianshu.com/p/bc351bdcafc9

相关文章

热门资讯

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
返回顶部