大家好，又見面了，
在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 = "https://www.cnblogs.com/softwarearch/archive/2022/09/06/操作型別，取值說明： 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 = "https://www.cnblogs.com/softwarearch/archive/2022/09/06/操作型別，取值說明： 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 = "https://www.cnblogs.com/softwarearch/archive/2022/09/06/操作型別", 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 = https://www.cnblogs.com/softwarearch/archive/2022/09/06/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介面中的描述內容已經同步更新為最新的內容，
完美，大功告成??????，
總結
好啦，關于如何通過自定義注解的方式擴展Swagger的能力讓Swagger支持自動從指定的列舉類生成介面檔案中的欄位描述的實作思路，這里就給大家分享到這里啦，關于本篇內容你有什么自己的想法或獨到見解么？歡迎在評論區一起交流探討下吧，
????啰嗦兩句
-
寫到這里忽然察覺到，其實 Swagger 會用很容易，但想用好卻還是需要一定功夫的，所以趁勢決定針對如何在專案中真正的用好Swagger再單獨的寫一篇檔案，近期會分享出來，感興趣的小伙伴可以關注下，避免迷路，??????
-
關于本文中涉及的演示代碼的完整示例，我已經整理并提交到github中，如果您有需要，可以自取：https://github.com/veezean/JavaBasicSkills
我是悟道，聊技術、又不僅僅聊技術~
如果覺得有用，請點贊 + 關注讓我感受到您的支持，也可以關注下我的公眾號【架構悟道】，獲取更及時的更新，
期待與你一起探討，一起成長為更好的自己，
本文來自博客園，作者：架構悟道，歡迎關注公眾號[架構悟道]持續獲取更多干貨，轉載請注明原文鏈接：https://www.cnblogs.com/softwarearch/p/16660562.html
轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/504677.html
標籤：其他