技術文章 » JAVA中自定義擴充套件Swagger的能力，自動生成引數取值含義說明，提升開發效率

JAVA中自定義擴充套件Swagger的能力，自動生成引數取值含義說明，提升開發效率

2022-09-06 12:02:16

大家好，又見面了。

在JAVA做前後端分離的專案開發的時候，伺服器端需要提供介面檔案供周邊人員做介面的對接指導。越來越多的專案都在嘗試使用一些基於程式碼自動生成介面檔案的工具來替代由開發人員手動編寫介面檔案，而Swagger作為一款優秀的線上介面檔案生成工具，以其功能強大、整合方便而得到了廣泛的使用。

在專案中有一種非常常見的場景，就是介面的請求或者響應引數中會有一些欄位的取值會限定為固定的幾個可選值之一，而在程式碼中這些可選值往往會通過定義列舉類的方式來承載，比如：

根據操作型別，過濾對應型別的使用者操作紀錄檔列表
如: http://127.0.0.1:8088/test/queryOperateLogs?operateType=2

這裡的請求引數operateType傳入的值需要在後端約定的取值範圍內，這個取值範圍的定義如下：

@Getter
@AllArgsConstructor
public enum OperateType {
    ADD(1, "新增或者建立操作"),
    MODIFY(2, "更新已有資料操作"),
    DELETE(3, "刪除資料操作"),
    QUERY(4, "查詢資料操作");

    private int value;
    private String desc;
}

這裡就需要我們在介面檔案裡面將此介面中operateType的可選值以及每個可選值對應的含義資訊都說明清楚，這樣呼叫方在使用的時候才知道應該傳入什麼值。

我們基於Swagger提供的基礎註解能力來實現時，比較常見的會看到如下兩種寫法：

  • 寫法1：介面定義的時候，指定入參的取值說明

介面URL中攜帶的請求入參資訊，通過@ApiImplicitParam註解來告訴呼叫方此介面允許接收的合法operateType的取值範圍以及各個取值的含義。

比如下面這種場景：

@GetMapping("/queryOperateLogs")
@ApiOperation("查詢指定操作型別的操作紀錄檔列表")
@ApiImplicitParam(name = "operateType", value = "操作型別，取值說明： 1，新增；2，更新；3，除；4，查詢", dataType = "int", paramType = "query")
public List<OperateLog> queryOperateLogs(int operateType) {
    return testService.queryOperateLogs(operateType);
}

這樣，在swagger介面上就可以顯示出欄位的取值說明資訊。

其實還有一種寫法，即在程式碼的入參前面新增@ApiParam註解的方式來實現。比如：

    @GetMapping("/queryOperateLogs")
    @ApiOperation("查詢指定操作型別的操作紀錄檔列表")
    public List<OperateLog> queryOperateLogs(@ApiParam(value = "操作型別，取值說明： 1，新增；2，更新；3，刪除；4，查詢") @RequestParam("type") int operateType) {
        return testService.queryOperateLogs(operateType);
    }

這樣也能達到相同的效果。

  • 寫法2：請求或者響應的Body體中解釋欄位的取值說明

對於需要使用json體進行傳輸的請求或者響應訊息體Model中，可以使用@ApiModelProperty新增含義說明。

@Data
@ApiModel("操作記錄資訊")
public class OperateLog {
    @ApiModelProperty("操作型別，取值說明： 1，新增；2，更新；3，刪除；4，查詢")
    private int operateType;
    @ApiModelProperty("操作使用者")
    private String user;
    @ApiModelProperty("操作詳情")
    private String detail;
}

同樣，在Swagger介面就可以清楚的知道每個欄位的具體含義與取值說明。

但是上面的兩個寫法，都存在著同一個問題，就是如果列舉類中的值內容含義有變更，比如OperateType列舉類中新增了一個BATCH_DELETE(5, "批次刪除"), 則必須手動去修改所有涉及的介面上的Swagger描述資訊。如果有大量場景都涉及此欄位，則要改動的地方就非常多，且極易漏掉（因為不好通過程式碼關聯關係直接搜尋到）。這樣對於開發人員維護起來的成本就會增加，久而久之會導致介面檔案的內容與實際程式碼處理情況不相匹配。

那麼，有沒有什麼簡單的方式，可以讓介面檔案自動根據對應列舉類的內容變更而動態變更呢？

Swagger沒有提供原生的此方面能力支援，但是我們可以通過一些簡單的方式對Swagger的能力進行擴充套件，讓Swagger支援我們的這種訴求。一起來看下如何實現吧。

擴充套件可行性分析

既然想要改變生成的Swagger檔案中指定欄位的描述內容，那麼首先就應該是要搞清楚Swagger中現在的內容生成邏輯是如何處理的。我們以@ApiParam為例進行分析。因為@ApiParam中指定的內容會被顯示到Swagger介面上，那麼在Swagger的框架中，一定有個地方會嘗試去獲取此註解中指定的相關欄位值，然後將註解的內容轉為介面上的檔案內容。所以想要客製化，首先必須要了解當前是如何處理的。

翻看Swagger的原始碼，發現在ApiParamParameterBuilder類中進行此部分邏輯的處理，處理邏輯如下：

看了下此類是ParameterBuilderPlugin介面的一個實現類，Swagger框架在遍歷並逐個生成parameter說明資訊的時候會被呼叫此實現類的邏輯來執行。

到這裡其實問題就已經很明顯了，我們可以自定義一個處理類並實現ParameterBuilderPlugin介面，然後將我們的訴求在自定義的處理類中進行實現，這樣不就可以實現我們的訴求了嗎？

相同的策略，我們可以找到處理@ApiImplicitParam、@ApiModelProperty對應的介面類。

根據上面的分析，我們只需要提供個自定義實現類，然後分別實現這幾個介面就可以搞定我們的訴求了。那應該如何進行封裝，將其作為一個通用能力供所有場景使用呢，下面詳細討論下。

自定義註解實現基於列舉類生成描述

前面已經找到了一種思路將我們的客製化邏輯注入到Swagger的檔案生成框架中進行呼叫，那麼下一步我們就得確認一種相對簡單的策略，告訴框架哪個欄位需要使用列舉來自動生成取值說明，以及使用哪個列舉類來生成。

這裡我們使用自定義註解的方式來實現。Swagger為不同的場景分別提供了@APIParam、@ApiImplicitParam、@ApiModelProperty等不同的註解，我們可以簡化下，提供一個統一的自定義註解即可。

比如：

@Target({ ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER })
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiPropertyReference {
    // 介面檔案上的顯示的欄位名稱，不設定則使用field本來名稱
    String name() default "";
    // 欄位簡要描述，可選
    String value() default "";
    // 標識欄位是否必填
    boolean required() default  false;
    // 指定取值對應的列舉類
    Class<? extends Enum> referenceClazz();
}

這樣呢，對於需要新增取值說明的欄位或者介面上，我們就可以新增@ApiPropertyReference並指定對應的列舉類即可。

比如下面這樣：

@Data
@ApiModel("操作記錄資訊")
public class OperateLog {
    @ApiPropertyReference(value = "操作型別", referenceClazz = OperateType.class)
    private int operateType;
    // ... 
}

上面範例程式碼中，OperateType是一個已經定義好的列舉類。現在又遇到一個問題，列舉類的實現形式其實也不一樣，要如何才能讓我們的自動內容生成服務知道獲取列舉類中的哪些內容進行處理呢？當然我們可以約定用於Swagger註解中的列舉類必須遵循某個固定的格式，但顯然這樣實施的難度就會提升，並非是我們想要的結果。

先來看下面給定的這個列舉類，其中包含order、value、desc三個屬性值，而value欄位是我們的介面欄位需要傳入的真實取值，desc是其對應的含義描述，那麼該如何讓我們自定義Swagger擴充套件類知曉應該使用value和desc欄位來生成檔案描述內容呢？

@Getter
@AllArgsConstructor
public enum OperateType {
    ADD(1, 11, "新增"),
    MODIFY(2, 22, "更新"),
    DELETE(3, 33, "刪除");
    private int order;
    private int value;
    private String desc;
}

答案其實不陌生，依舊是自定義註解！只要提供個自定義註解，然後新增到列舉類上，指定到底使用列舉類中的哪個欄位作為value值，以及哪個欄位用作含義描述desc欄位值就行了。

@Target({ ElementType.TYPE })
@Retention(RetentionPolicy.RUNTIME)
public @interface SwaggerDisplayEnum {
    String value() default "value";
    String desc() default "desc";
}

這樣，在列舉類上新增下@SwaggerDisplayEnum並指定下欄位的對映，即可用於Swagger註解中：

到這裡呢，我們需要的資料來源以及取值轉換規則就已經全部確定，剩下的就是如何將一個列舉類中需要的值與描述欄位給拼接成想要的內容了。因為是通用能力，所以此處需要通過反射的方式來實現：

private String generateValueDesc(ApiPropertyReference propertyReference) {
    Class<? extends Enum> rawPrimaryType = propertyReference.referenceClazz();
    SwaggerDisplayEnum swaggerDisplayEnum = AnnotationUtils.findAnnotation(rawPrimaryType,
            SwaggerDisplayEnum.class);
    String enumFullDesc = Arrays.stream(rawPrimaryType.getEnumConstants())
            .filter(Objects::nonNull)
            .map(enumConsts -> {
                Object fieldValue = ReflectUtil.getFieldValue(enumConsts, swaggerDisplayEnum.value());
                Object fieldDesc = ReflectUtil.getFieldValue(enumConsts, swaggerDisplayEnum.desc());
                return fieldValue + ":" + fieldDesc;
            }).collect(Collectors.joining(";"));
    return propertyReference.value() + "(" + enumFullDesc + ")";
}

測試下輸出如下面的格式，自動將列舉類中所有的列舉值及其描述資訊都展示出來了。

(1:新增;2:更新;3:刪除)

實現自定義擴充套件處理器

至此呢，我們已經做好了全部的準備工作，下面就可以按照前面分析的策略，來自定義一個實現類去實現相關介面，將我們的處理轉換邏輯注入到Swagger框架中去。

@Component
@Primary
public class SwaggerEnumBuilderPlugin implements ModelPropertyBuilderPlugin, ParameterBuilderPlugin {
    @Override
    public void apply(ModelPropertyContext context) {
        // Model中field欄位描述的自定義處理策略
    }
    @Override
    public void apply(ParameterContext parameterContext) {
        // API中入參的自定義處理策略
    }
    @Override
    public boolean supports(DocumentationType delimiter) {
        return true;
    }
}

下面只需要在apply方法中補充上我們的自定義處理邏輯即可。

自動生成API入參的取值說明

前面已經講了如何將指定的列舉類中的列舉值生成為描述字串，在這裡我們直接呼叫，然後將結果設定到context上下文中即可。

@Override
public void apply(ParameterContext context) {
    ApiPropertyReference reference =
            context.getOperationContext().findAnnotation(ApiPropertyReference.class).orNull();
    String desc = generateValueDesc(reference);
    if (StringUtils.isNotEmpty(reference.name())) {
        context.parameterBuilder().name(reference.name());
    }
    context.parameterBuilder().description(desc);
    AllowableListValues allowableListValues = getAllowValues(reference);
    context.parameterBuilder().allowableValues(allowableListValues);
}

自動生成Model中欄位取值說明

同樣的策略，我們處理下資料實體類中的field對應的含義說明。

@Override
public void apply(ModelPropertyContext modelPropertyContext) {
    if (!modelPropertyContext.getBeanPropertyDefinition().isPresent()) {
        return;
    }
    BeanPropertyDefinition beanPropertyDefinition = modelPropertyContext.getBeanPropertyDefinition().get();
    // 生成需要拼接的取值含義描述內容
    String valueDesc = generateValueDesc(beanPropertyDefinition);
    modelPropertyContext.getBuilder().description(valueDesc)
            .type(modelPropertyContext.getResolver()
                    .resolve(beanPropertyDefinition.getField().getRawType()));
}
}

效果演示

到這裡呢，程式碼層面的處理就全部完成了。接下來執行下程式，看下效果。先來看下API介面中入參的含義描述效果：

從介面效果上可以看出，不僅自動將取值說明描述給顯示出來，同時介面調測的時候，輸入框也變為了下拉框 （因為我們自動給設定了allowableValues屬性），只能輸入允許的值。同樣的，再來看下Model中的欄位的含義說明描述效果：

可以看到，介面檔案中的引數描述資訊中，已經自動帶上了列舉類中定義的候選取值內容與說明。我們僅修改下列舉類中的內容，其餘地方不做修改，再次看下介面，發現Swagger介面中的描述內容已經同步更新為最新的內容。

完美，大功告成