Swagger扩展用于动态显示Enum的属性说明

3,177次阅读
2条评论

前言

恍恍惚惚已然有两月之久没写博文了,现在是打开电脑放佛就像是肚子里面一点儿墨水都没有,不知思绪。

就不发表那么多的感言了,进入本文的正题:对于 Swagger 想必大家应该都比较熟悉,在线 API 文档生成的佼佼者(如果不知道,请 点此进行 了解),但是 Swagger 对于 Enum 的属性支持不太好,不能够在文档的 api 参数列表中展示参数值以及参数说明,这样就会导致前后端开发人员增加沟通成本,所以我们需要进行扩展。
Swagger

正文

基础配置

博主是参考的掘金上一位作者发表的 《swagger 动态显示枚举内容 + 数值类型空指针异常统一控制》 进行基础的配置,大家首先可以先参考这篇文章,再做好文章内的配置后再进行以下操作。

增加展示枚举属性

我们需要在 api 文档上显示这个枚举的标题,所以我们需要扩展一下 @SwaggerDisplayEnum 注解,新增 value 属性:

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

这样我们在使用 @SwaggerDisplayEnum 注解的时候需要配置当前这个枚举的名称,另外对于原作者给的方式获取的 name 值,而我用的 Mybatis-Plus 枚举映射要传递枚举的名称,所以要获取枚举的名称,所以大家将其中的:

value = valueField.get(item).toString();
// 以及
joinText = mField.get(context.getBuilder()) + joinText;

改成:

value = item.toString();
// 以及
joinText = swaggerDisplayEnum.value() + joinText;
不过要值得注意的是,对于目标解析枚举要重写toString(),其返回的内容为this.name()

到这步就可以实现我们需要的效果了,如下:
Swagger

7
憧憬Licoy
版权声明:本站原创文章,由 憧憬Licoy 2019-11-22发表,共计913字。
转载说明:除特殊说明外本站文章皆由CC-4.0协议发布,转载请注明出处。
评论(2条评论)
验证码
载入中...
武汉空调维修 评论达人 LV.1
2019-11-28 09:59:56 回复

写的不错,实用

WindowsWindowsChromeChrome63.0.3239.132
repostone 评论达人 LV.1
2019-11-23 16:47:41 回复

非技术的路过。

WindowsWindowsChromeChrome78.0.3904.87