Swagger3注解使用

这里只简单的说一下swagger的传值，返回值时注解的使用演示。相关注解及说明见其他文章

接收参数方式1

我们常规接收参数，可以使用一个类，类里面把属性作为接收的参数，使用注解对属性进行说明。但是这种传参方式，我调试的时候，支持前端的传参方式为：form-data

例子如下：

因为这种方式我们用的不多，所以这里就不展开来讲

一般我们前端都是传json数据过来后端，后端接收参数是直接用JSONObject或Map所以主要讲一下第二种

接收参数方式2

前端传参：json

后端接收：jsonObject或Map

对于这种JSONObject接收参数的，我们不能用第一种方式，此时应该用另外两个注解来实现

注意：dataType属性默认是String，如果要换成其他，比如int属性，不能直接写int或Interger，一定要加上全类名，不然会被解析成string类型。

代码如下：

 1      /**
 2       * 测试接口
 3       *
 4       * @param jsonObject 前端传过来的参数
 5       * @return 无
 6       */
 7      @PostMapping("/test")
 8      @ApiOperation(value = "测试接口", httpMethod = "POST", notes = "测试，这是一个后端的测试接口")
 9      @ApiImplicitParams({
10              @ApiImplicitParam(value = "这是具体的参数1说明", name = "parm1", required = true, dataType = "String",
11                      paramType = "query"),
12              @ApiImplicitParam(value = "参数二是string类型", name = "parm2", required = true, dataType = "String",
13                      paramType = "query"),
14              @ApiImplicitParam(value = "参数三是int类型", name = "parm3", required = true, dataType = "java.lang.Integer",
15                      paramType = "query"),
16              @ApiImplicitParam(value = "参数四是布尔类型", name = "parm4", required = true, dataType = "java.lang.Boolean",
17                      paramType = "query"),
18              @ApiImplicitParam(value = "参数五：0表示成功，1表示失败", name = "parm5", required = true, dataType = "String",
19                      paramType = "query")
20      })
21      public JSONObject testParm(JSONObject jsonObject) {
22  ​
23          return null;
24  ​
25      }
26  ​
27  }

这样子看，可能显得代码略显臃肿，但是我们写代码的时候，把它折叠起来就好了，效果如下

接下来，看一下swagger中的具体效果图

响应参数

请求参数我们了解了，接下来我们看一下响应参数，首先所有的响应都要基于ResponseVo这个类。

 1 @Data
 2  @ApiModel()
 3  public class ResponseVo<T> implements Serializable {
 4      @ApiModelProperty(value = "默认时间")
 5      private String defaultTimeZone;
 6      @ApiModelProperty(value = "成功为1，失败为0")
 7      private Integer result;
 8      @ApiModelProperty(value = "返回值信息")
 9      private T data;
10      @ApiModelProperty(value = "返回给前端的语言，默认是：zh_CN")
11      private String lang;
12      @ApiModelProperty(value = "时间，默认是：Asia/Shanghai")
13      private String userTimeZone;
14  ​
15  ​
16      public ResponseVo(Integer result, T data) {
17          this(result, "Asia/Shanghai", "Asia/Shanghai", "zh_CN", data);
18      }
19  ​
20  ​
21      public ResponseVo(Integer result, String defaultTimeZone, String userTimeZone, String lang, T data) {
22          this.defaultTimeZone = defaultTimeZone;
23          this.result = result;
24          this.userTimeZone = userTimeZone;
25          this.lang = lang;
26          this.data = data;
27      }
28  ​
29      @Override
30      public String toString() {
31          return JSONObject.toJSONString(this);
32      }
33  }

swagger效果图

swagger调试效果图：

返回实列1

ok，接下来，我们进行一些复杂的操作，我们尝试模拟下面这里复杂的类型返回

可以看出 formFieldDataOrder是一个数组

tableData是一个对象

formFieldData是一个对象

java代码

首先创建两个类，然后在ResponseDataVo里面定义三个属性，，其中数组的用定义为List，对象定义为具体的类

注意：定义为返回值的类，一定要加上@ApiModel注解

返回值设置

swagger效果：

返回实列2

接下来，我们往里面添加数据

老样子，创建IslandId类和Name类，在FormFieldData类中设置这两个对象属性

设置对应的返回值

swagger效果图

swagger调试结果图

返回实列3

接下来，我们完善一下Island里面的属性

定义IslandId对象里面的属性

设置对应的值

swagger效果图

调试结果

到这里，swagger注解的使用算是入门了，注意，其中还是有很多细节要注意的，由于时间问题，没有一一列举出来。欢迎大家点评指正。