Springboot中集成Swagger2框架的方法

程序员文章站 2023-12-05 16:54:16

摘要：在项目开发中，往往期望做到前后端分离，也就是后端开发人员往往需要输出大量的服务接口，接口的提供方无论是是java还是php等语言，往往会要花费一定的精力去写接口文档，...

摘要：在项目开发中，往往期望做到前后端分离，也就是后端开发人员往往需要输出大量的服务接口，接口的提供方无论是是java还是php等语言，往往会要花费一定的精力去写接口文档，比如a接口的地址、需要传递参数情况、返回值的json数据格式以及每一个字段说明、当然还要考虑http请求头、请求内容等信息。随着项目的进度快速高速的迭代，后端输出的接口往往会面临修改、修复等问题，那也意味着接口文档也要进行相应的调整。接口文档的维护度以及可读性就大大下降。

既然接口文档需要花费精力去维护，还要适当的进行面对面交流沟通，我们何不想一个办法，第一：可以不用写接口文档；第二：前端与后端沟通接口问题的时候，后端是否可以提供一个url，在这个url中罗列出所有可以调用的服务接口，并在每个服务接口中罗列出参数的说明，返回值的说明，第三：后端接口如果能模拟调用就所有问题都解决了。本文我们重点讲解一下sringboot中集成swagger2框架。

1.1. 添加swagger2依赖

在项目的pom.xml文件中增加如下的依赖。

<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>

首先，我们需要建立一个启动类，代码如下：

@springbootapplication
public class application {
 public static void main(string[] args) {
 springapplication.run(application.class, args);
 }
}

然后在上述类的同级目录中新建swagger2的配置类如下所示：

@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. 新增文档说明

上述的类声明之后，我们其实就可以直接调用了，但是为了增加文档的可读性，我们还是需要在接口中增加一些说明，我们先写一个控制器如下所示：

@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，访问，如下图所示：

Springboot中集成Swagger2框架的方法