Swagger使用介绍三之为Controller中参数添加JSONObject类型字段说明

• 回顾

上文中我们介绍了如果给Controller中的参数添加字段说明：https://blog.csdn.net/shangcunshanfu/article/details/100838687，也留下了一个问题，那就是如何给JSONObject类型的参数添加字段说明，本章就来进行介绍

• 说明

Swagger其实是没有针对JSONObject添加字段说明功能的，这也很好理解，因为Swagger并没有义务为jackson或是fastjson或是其它json序列化工具添加一个专门的字段说明功能。要对JSONObject类型参数添加字段说明，本人自行编写了一个Swagger的扩展包，用于提供该功能。

 

1. 1. 下载源码包

下载地址https://github.com/ShangCunShanFu/swagger-extension。

下载完成后，打包并引入自己的工程中。

在配置文件中添加如下配置：

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",
            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实体说明", 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",
                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. 实体当中存在子级

为处理实体中存在子级结构的问题，在@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页面的效果如下：

 

图5. 4

从图5.4即可明显看出子级结构的存在。

这样的作法让接口上的注解看起来很臃肿，其实这是有必要的，可是不必去担心和纠结的。当使用Swagger的@ApiModel注解时，也需要定义相同多的参数说明。只不过这些说明被放在了某一个类中进行，并没有体现在Controller的接口上而已。