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的接口上而已。