SpringBoot整合Swagger2实例方法

在进行软件开发的时候免不了要写接口文档，这些文档需要明确写出接口的类型、请求的url、传参和返回值格式等信息，用于和前端交互或者提供给测试进行接口测试。但是手写文档一方面带给我们很大的工作量，另一方面如果接口有变更则需要频繁修改并且发给相关的人，无形中增加了工作量。小编为大家介绍一个生成文档的工具swagger，上手简单，学习成本低，非常适合开发springboot项目，现在就跟着小编一起学习吧。

首先需要在pom文件中加入swagger2的依赖，依赖的jar包如下图所示。

<dependency>
 <groupid>io.springfox</groupid>
 <artifactid>springfox-swagger2</artifactid>
 <version>2.8.0</version>
</dependency>
<dependency>
 <groupid>io.springfox</groupid>
 <artifactid>springfox-swagger-ui</artifactid>
 <version>2.8.0</version>
</dependency>

编写swagger配置类swagger2config，在类上增加@configuration和@enableswagger2注解，表明这是一个配置类，同时开启swagger。如下的信息可以根据具体情况修改。

@bean
public docket api() {
  return new docket(documentationtype.swagger_2)
      .apiinfo(apiinfo())
      .select()
      // 自行修改为自己的包路径
      .apis(requesthandlerselectors.basepackage("com.spring.jpa.user"))
      .paths(pathselectors.any())
      .build();
}

private apiinfo apiinfo() {
  return new apiinfobuilder()
      .title("swagger-api文档")
      .description("用户信息相关")
      //服务条款网址
      .termsofserviceurl("https://baidu.com")
      .version("1.0")
      .contact(new contact("nwsl", "http://baidu.com", "[e-mail]"))
      .build();
}

 

接下来我们需要在controller层添加注解，@api(value="/test1", tags="测试用户接口模块")， @api这个注解是用在请求的类上，表示对类的说明，其中tags="说明该类的作用，可以在ui界面上看到的注解"，value="该参数没什么意义，在ui界面上也看到，所以不需要配置"。该注解的使用如下图所示。

 

接下来我们需要在方法上添加注解了，如下所示，@apioperation、@apiimplicitparams、@apiimplicitparam的作用如下图所示。@apiresponses：用在请求的方法上，表示一组响@apiresponse：用在@apiresponses中，一般用于表达一个错误的响应信息。

在方法中的使用如下图所示。

@apioperation(value="添加用户信息", notes = "添加用户信息")
@apiimplicitparams({
    @apiimplicitparam(name = "name", value = "用户姓名", required = true, datatype = "string",paramtype = "query"),
    @apiimplicitparam(name = "age", value = "用户年龄", required = true,paramtype = "query")
})

注意如果是integer类型，那datatype = "integer"就可以省略了，写上了反而在生成的文档调用的时候出错。

接下来我们介绍传实体类参数的注解怎么写，要使用到@apimodel、@apimodelproperty，具体的用法如下图所示。在接收参数的实体类上我们需要添加这两个注解，如下图所示。

接口上注解写完之后，我们启动服务，然后打开swagger的ui页面，注意8091端口是我本机服务启动的端口，请求的地址如下图所示。我们可以看到每个controller类都生成了文档，usercontroller我们增加了类的注释。

接下来我们测试usercontroller中的接口，如下图所示，生成了usercontroller所有的接口文档，我们首先来看添加用户接口，如下图所示，为什么integer类型的age字段，在生成的接口文档中参数类型变成了ref呢？上文提到过的，在写注解的时候，datatype = "integer"要省略掉，不然会出现这个问题。正确的如下所示，可以看到age为integer类型了。

我们可以看到在接口的右侧有try it out，点击该按钮进入到调用页面。在如下的页面填写完参数之后执行execute即可，还是age参数ref的问题，此时执行会提示错误，要把注释中的integer类型去掉，在执行即可。

接下来我们看一个get请求，这个请求不需要传参，直接执行即可，结果如下图所示。我们可以看到swagger生成的restful形式的接口文档，非常方便调试。

接下来我们执行update的接口，这是上面我们用实体类接收参数的方法，可以看到参数的例子，我们修改完参数值后执行即可。以上swagger2与springboot就集成完了。