返回給前端樣式數據整合Swagger

對於前端樣式整合swagger，只對接口做增強，不對接口邏輯做修改，當json樣式拼接完成，我們把json轉為對應的實體類即可。

前端json樣式對象構造參考：https://workshops.otrs365.cn/web/#/132?page_id=1248

針對前端樣式，此次抽出5個公共模塊類，下面對這些類進行展開敘述

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

ReturnData 返回給前端的數據(最外層)

ReturnData<T,L,O>

/**
 * @param <T> FormStyle里面Data的泛型
 * @param <L> ListHead里面的字段的具體屬性
 * @param <O> OverviewList,一般與數據庫表屬性對應
 * @Description:
 * @author: 張重虎
 * @Date: 2021/6/2 9:31
 * @Copyright: Xi'an Dian Tong Software Co., Ltd. All Rights Reserved.
 * @Version 1.0
 */
@Data
@ApiModel
public class ReturnData<T,L,O> {
    @JsonProperty("tableStyle")
    @ApiModelProperty(value = "表格樣式")
    private Tablestyle<L,O> tablestyle;
    @ApiModelProperty(value = "表單樣式")
    @JsonProperty("formStyle")
    private Formstyle<T> formstyle;
}

 

ReturnData<T,L,O>使我們能高度自定義返回的樣式

前端界面以簡單的FormStyle和TableStyle展開拼接

 

 

FormStyle （返回給前端的表單樣式）

FormStyle里面有兩個基本屬性: data和order。data里面是一個個order對象，對象里面是具體的屬性

Formstyle<T>

@lombok.Data
@ApiModel
public class Formstyle<T> {
    @ApiModelProperty(value = "頁面表單字段具體樣式")
    private T data;
    @ApiModelProperty(value = "頁面表單展示字段")
    private List<String> order;
}

 

 

Data對應一個泛型，泛型里面定義Data的基本屬性，一般以下屬性就夠了，多的在繼承這個類，然后進行擴展即可

FormStyleDataGeneric:

@Data
@ApiModel
public class FormStyleDataGeneric {
    @JsonProperty("default")
    @ApiModelProperty(value = "默認值")
    private String defaults;

    @ApiModelProperty(value = "展示")
    private String display;

    @JsonProperty("promptCode")
    @ApiModelProperty(value = "0，不做提示；1，展示在文本框內；2，展示在字段下方；,3，展示圖標在字段尾部進行提示；4，以紅色提示展示在字段下方")
    private int promptcode;

    @ApiModelProperty(value = "表單提交到后台的 Key")
    private String name;

    @ApiModelProperty(value = "可選項")
    private JSONObject options;

    @JsonProperty("disabledClear")
    @ApiModelProperty(value = "可清除/可擦除")
    private int disabledclear;

    @JsonProperty("promptMessage")
    @ApiModelProperty(value = "提示信息")
    private String promptmessage;

    @ApiModelProperty(value = "翻譯信息展示在左側的 Label 中")
    private String label;

    @ApiModelProperty(value = "字段類型。文本：Text，下拉選：Dropdown，樹：SelectTree，復選框：Checkbox，時間類型：DateTime（年月日-時分秒），Date（年月日）")
    private String type;
}

 

FormStyleDataGeneric里面的屬性對應前端界面效果

 

 

Formstyle<T> ，T 如果FormStyleDataGeneric里面的屬性不滿足，則自定義一個即可

使用方法 Formstyle<FormStyleDataGeneric>

TableStyle （返回給前端的表格樣式）

TableStyle<L,O>

@Data
@ApiModel
public class Tablestyle<L,O> {
    @JsonProperty("PreferenceFields")
    @ApiModelProperty(value = "表格中表頭字段")
    private List<String> preferencefields ;

    @ApiModelProperty(value = "可配置數據")
    private List<String> configData ;


    @ApiModelProperty(value = "表格數據總數")
    private int total;

    @JsonProperty("OverviewList")
    @ApiModelProperty(value = "表格中具體某條數據")
    private List<O> overviewlist;

    @JsonProperty("ListHeader")
    @ApiModelProperty(value = "表頭字段的具體屬性")
    private L listheader;
}

 

TableStyle<L,O>對應頁面屬性說明

 

 

看得出來，TableStyle<L,O>里面有兩個泛型，如果基本的屬性滿足不了我們，我們自定義一個類，然后傳進去即可。另外，泛型O一般是對應我們數據表的那個dao實體類，直接傳進去即可

泛型L,L代表ListHeader里面的屬性，就是表頭字段的屬性，在小島這里看不出來，我們用另一個界面對這些屬性進行解讀。

定義ListHeader<T>的時候，我們根據數據表dao去定義屬性，然后加上泛型T即可

ListHeader<T> , 這個T我們一般傳ListHeaderGeneric就夠了，如果需要添加其他字段，就自定義一個泛型，往里面傳即可

@Data
@ApiModel
public class Listheader<T> {
    @ApiModelProperty(value = "模板")
    private T template;

    @ApiModelProperty(value = "流程")
    private T process;

    @JsonProperty("featureCode")
    @ApiModelProperty(value = "特征碼")
    private T featurecode;

    @JsonProperty("communicationConfigName")
    @ApiModelProperty(value = "通訊地址名稱")
    private T communicationconfigname;

    @JsonProperty("dataPackageName")
    @ApiModelProperty(value = "數據包名稱")
    private T datapackagename;

    @JsonProperty("changeBy")
    @ApiModelProperty(value = "修改者")
    private T changeby;

    @JsonProperty("changeTime")
    @ApiModelProperty(value = "修改時間")
    private T changetime;

    @JsonProperty("createBy")
    @ApiModelProperty(value = "創建者")
    private T createby;

    @JsonProperty("createTime")
    @ApiModelProperty(value = "創建時間")
    private T createtime;

    @ApiModelProperty(value = "名稱")
    private T name;

    @JsonProperty("operationType")
    @ApiModelProperty(value = "操作類型")
    private T operationtype;

    @ApiModelProperty(value = "備注")
    private T comment;

    @ApiModelProperty(value = "說明")
    private T direction;
}

 

ListHeaderGeneric

@Data
@ApiModel
public class ListHeaderGeneric {
    @JsonProperty("SortBy")
    @ApiModelProperty(value = "排序:0可排序，1不可排序")
    private int sortby;

    @JsonProperty("Label")
    @ApiModelProperty(value = "標簽")
    private String label;

    @JsonProperty("FilterKey")
    @ApiModelProperty(value = "過濾key，代表該字段可進行過濾")
    private String filterkey;
}

 

 

 

TableStyle<L,O>使用方法TableStyle<ListHeader<ListHeaderGeneric>,Overviewlist>

特殊情況

返回的數據比ReturnData更多

以Communication通訊地址為例

ps:以后統一返回首字母大寫的駝峰命名，比如FormStyle而不是formStyle

 

 

數據除了formStyle和tableStyle，還額外多了個myParameter

 

 

對應這種情況，我們繼承ReturnData<T, L, O>進行擴展即可,如果還需對增加的屬性進行說明，就在定義一個泛型即可

CommunicationTableData

@Data
@EqualsAndHashCode(callSuper = true)
@ApiModel
public class CommunicationTableData<T, L, O> extends ReturnData<T, L, O> {
    @ApiModelProperty(value = "本島相關信息(小島id,小島地址)")
    private JSONObject myParameter;
}

 

返回的數據為里面那層(Tablestyle)

比如數據包里面

 

 

看着像Tablestyle，但是又比Tablestyle多了幾個屬性，那我們就可以自定義一個ReturnData,讓它直接繼承Tablestyle，再做擴展

或者不繼承TableData，直接寫一個ReturnData類，里面包含這些屬性

@Data
@ApiModel
public class TableData<L,S,O> {
    @JsonProperty("PreferenceFields")
    @ApiModelProperty(value = "默認展示的表頭信息")
    private List<String> preferencefields ;

    @ApiModelProperty(value = "搜索表單字段集合")
    private S searchFormDataOrder ;

    @ApiModelProperty(value = "可配置數據")
    @JsonProperty("PreferenceDisable")
    private String preferenceDisable ;


    @ApiModelProperty(value = "表格數據總數")
    private int total;

    @ApiModelProperty(value = "表格中具體某條數據")
    @JsonProperty("OverviewList")
    private List<O> Overviewlist;

    @JsonProperty("ListHeader")
    @ApiModelProperty(value = "表頭數據集合")
    private L listheader;
}

 

返回的數據為里面那層(Formstyle)

比如通訊地址編輯界面

 

 

看着結構就是Formstyle，但是ReturnData中的兩個屬性都是Formstyle(一般是一個Formstyle和一個Tablestyle)，針對這種情況，我們直接寫一個新的ReturnData

/**
 * @param <T> BaseGenericEditData
 * @param <L> CommunicationGenericEditData
 * @Description:
 * @author: 張重虎
 * @Date: 2021/6/2 15:43
 * @Copyright: Xi'an Dian Tong Software Co., Ltd. All Rights Reserved.
 * @Version 1.0
 */
@Data
@ApiModel
public class CommunicationEditData<T,L> {

    @ApiModelProperty(value = "基礎樣式")
    @JsonProperty("base")
    private Formstyle<T> base;

    @ApiModelProperty(value = "通訊地址樣式")
    @JsonProperty("communicationConfig")
    private Formstyle<L> communicationConfig;
}

 

但是這兩個Formstyle里面的屬性不一致，所以我們需要分開來定義兩個泛型

 

 

上面兩個泛型，其實都是可以通過數據表的dao實體類控制，直接傳實體類進去即可。但是為了方便區分，我定義了兩個泛型 <T> BaseGenericEditData，<L> CommunicationGenericEditData

BaseGenericEditData:

@Data
@ApiModel
public class BaseGenericEditData<T> {

    @ApiModelProperty(value = "名稱")
    private T name;

    @ApiModelProperty(value = "是否用與中聯BH")
    @JsonProperty("isOnlyForZlbh")
    private T isonlyforzlbh;

    @ApiModelProperty(value = "遠程系統id")
    @JsonProperty("remoteSystemId")
    private T remotesystemid;

    @ApiModelProperty(value = "通訊地址")
    @JsonProperty("communicationAddress")
    private T communicationaddress;

    @ApiModelProperty(value = "通訊key")
    @JsonProperty("communicationKey")
    private T communicationkey;

    @ApiModelProperty(value = "有效id")
    @JsonProperty("validId")
    private T validid;
}

 

CommunicationGenericEditData:

@Data
@ApiModel
public class CommunicationGenericEditData<T> {
    @JsonProperty("requestTimes")
    @ApiModelProperty(value = "每分鍾最大請求次數")
    private T requesttimes;

    @ApiModelProperty(value = "發送超時時限")
    private T overtime;

    @ApiModelProperty(value = "是否重連")
    @JsonProperty("isReconnection")
    private T isreconnection;

    @ApiModelProperty(value = "是否自動重連")
    @JsonProperty("reconnectionTimes")
    private T reconnectiontimes;

    @ApiModelProperty(value = "自動重連次數")
    @JsonProperty("reconnectionInterval")
    private T reconnectioninterval;

    @ApiModelProperty(value = "日志等級")
    @JsonProperty("logLevel")
    private T loglevel;
}

 

如小島的轉入轉出規則中，preferenceFields在前端展示成了小寫。

 

 

而模板中PreferenceFields是大寫，對於這種情況，是以前遺留的問題，沒有較好的規范，導致大小寫很隨意。

 

 

對於這種情況，我們肯定不能因為一個字段就重寫整個類。這時候，我們只需要繼承Tablestyle，然后把改字段重寫即可。

 

 

 

返回的數據為其他數據

其他復雜的界面，如果包含了基礎的ReturnData屬性，先繼承，在寫一個ReturnData類做其他擴展屬性，否則根據具體情況，自定義ReturnData

舉例1

小島通訊地址：getFromDataForAddOrUpdata

 

 

沒整合Swagger之前，返回值泛型是JSONObjec，直接返回jsonRes

 

 

整合之后，泛型JSONObject就變為具體的對象Communication< >對象