Swagger使⽤介绍三之为Controller中参数添加JSONObject类
油耗计算字段说明
回顾
说明
Swagger其实是没有针对JSONObject添加字段说明功能的,这也很好理解,因为Swagger并没有义务为jackson或是fastjson或是其它json序列化⼯具添加⼀个专门的字段说明功能。要对JSONObject类型参数添加字段说明,本⼈⾃⾏编写了⼀个Swagger的扩展包,⽤于提供该功能。
1.
1. 下载源码包
下载完成后,打包并引⼊⾃⼰的⼯程中。
在配置⽂件中添加如下配置:
hgd11-swagger:
baseControllerPackage: 换成controller包的要⽬录
1.
1. 使⽤⽅法
1.
1.
1. @Hgd11SwaggerModel
该注解⽤来对实体进⾏说明,类似于Swagger提供的@ApiModel。⽤法如下:
@Hgd11SwaggerModel(description = "测试Hgd11SwaggerModel实体说明", index = "hgd11TestEntity",
properties = @Hgd11SwaggerProperties(value = {
@Hgd11SwaggerProperty(
name = "id",
index = "userId",
description = "⽤户ID",
dataType = "integer",
required = true,
example = "1"),
@Hgd11SwaggerProperty(
name = "name",
index = "userName",
description = "⽤户姓名",
dataType = "String",
jeep指南针example = "wangkaige"), }))
菲亚特论坛@PostMapping("/form")
@ApiOperation("测试Hgd11SwaggerModel")
public JSONObject Hgd11SwaggerModel(){
return new JSONObject();
}
代码5.1
该注解中有⼀个description属性,值 为”测试hgd11SwaggerModel实体说明”,该属性就是对⼀个实体的说明。在真实开发中,该值可以是”⽤户说明”、”部门说明”等。
在Swagger页⾯上效果如下:
图5. 1
从图5.1可以看出,实现了与图1.1相同的效果。
1.
1.
1. @Hgd11SwaggerProperties及@Hgd11SwaggerProperty注解
对JSONObject实体⾥需要封装的字段进⾏说明。
以代码5.1及图5.1为例,代码中添加了两个字段,“id”,“name”,在图5.1中也得到了字段相应的说明,其字段类型及是否必传也体现了出来。
1.
1.
1. @Hgd11SwaggerParameter
当JSONObject或是Map类型实体作为参数时,对实体中的字段作说明。
@PostMapping("/hgd11SwaggerParameter")
public TestEntity hgd11SwaggerParameterTest(
@Hgd11SwaggerParameter(description = "测试Hgd11SwaggerParameter实体说明",model = @Hgd11SwaggerModel(description = "测试Hgd11SwaggerModel实        properties = @Hgd11SwaggerProperties(value = {
@Hgd11SwaggerProperty(
name = "id",
index = "userId",
description = "⽤户ID",
dataType = "integer",
required = true,
example = "1"),
@Hgd11SwaggerProperty(
name = "name",
index = "userName",
description = "⽤户姓名",
dataType = "String",
example = "wangkaige"), })))
JSONObject param
){
return new TestEntity();
}
代码5.2
代码中有⼀个名为param的JSONObject实体作为接⼝的参数,当在该参数是添加了@Hgd11SwaggerParameter注解以后,就表⽰该实
体拥有了id,name两个属性。在Swagger中的展现如下:
图5. 2
可以看到,在注解中为实体添加的两个字段成功的展现在了Swagger页⾯上。
@Hgd11SwaggerParameter⾥⾯封装了@Hgd11SwaggerModel注解。
1.
1.
1. @Hgd11SwaggerModelRef及@Hgd11SwaggerParameterRef
当在Controller中已经使⽤@Hgd11SwaggerModel定义了某个实体的时候,再次使⽤到该实体时,可使⽤@Hgd11SwaggerModelRef
引⽤之前定义过的实体。如果要把之前的实体引⽤作为参数,则配合使⽤@Hgd11SwaggerParameterRef即可。代码如下:
@Hgd11SwaggerModelRef(ref = "hgd11TestEntity")
@ApiOperation("测试Ref")
@PostMapping("/hgd11SwaggerModelRef")
public JSONObject hgd11SwaggerModelRef(
@Hgd11SwaggerParameterRef(
description = "测试Hgd11SwaggerParameterRef实体说明",
model = @Hgd11SwaggerModelRef(
ref = "hgd11TestEntity")) JSONObject param) {
return new JSONObject();}
代码5.3
在代码5.3中使⽤了@Hgd11SwaggerModelRef注解及@Hgd11SwaggerParameterRef注解。这两个注解都只有⼀个属性,那就是ref,当需要引⽤某⼀个已定义的实体时,将已存在实体的index属性赋予ref即可。如代码5.3中的”hgd11TestEntity”。
图5. 3
从图5.3可以看出,传参及响应,都成功对参数进⾏了说明。
1.
1.
1. 实体当中存在⼦级aplus>改装电动车
为处理实体中存在⼦级结构的问题,在@Hgd11SwaggerProperty注解中,有⼀个属性叫“children”。该属性是⼀个数组,在该处指定⼦级结构即可。代码如下:
@PostMapping("/hgd11SwaggerParameter")
@ApiOperation("测试hgd11SwaggerParameter")
public TestEntity hgd11SwaggerParameterTest(
@Hgd11SwaggerParameter(description = "测试Hgd11SwaggerParameter实体说明",
model = @Hgd11SwaggerModel(description = "测试Hgd11SwaggerModel实体说明",
index = "hgd11TestEntityChild",
properties = @Hgd11SwaggerProperties(value = {
@Hgd11SwaggerProperty(
name = "id",
index = "userId",
description = "⽤户ID",
dataType = "integer",
required = true,
example = "1"),
@Hgd11SwaggerProperty(
name = "dept",
index = "userDept",
description = "⽤户所在部门",
children = {"deptId","deptName"}),
@Hgd11SwaggerProperty(
name = "id",
index = "deptId",
好运轮胎description = "部门ID",
dataType = "integer",
required = true,
example = "1"),
@Hgd11SwaggerProperty(
name = "name",
index = "deptName",
description = "部门名称",
dataType = "String",
required = true,
example = "开发部"),
})))
JSONObject param
){
return new TestEntity();
}
代码5.4
代码中index=userDept的属性,有⼀个⼦级,该⼦级有两个属性,deptId及deptName。然后再定义两个index=deptId及
index=deptName的属性,即可完成⼦级结构的创建。
需要注意的是,进⾏属性之间⼦级关系绑定的,是index属性,⽽不是name属性。不同属性之间name属性可以重名,但index属性的值必须唯⼀。完成后Swagger页⾯的效果如下: