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页⾯的效果如下：