在JAVA前后端分离项目开发中，服务端通过接口文档为周边人员提供对接指导，Swagger作为一款功能强大、集成方便的在线接口文档生成工具，广泛应用于项目中。当接口请求或响应参数中存在限定的可选值时，通常通过枚举类承载，例如根据操作类型过滤用户操作日志列表。在接口文档中明确这些可选值及其含义至关重要。

常见的做法是使用@ApiImplicitParam或@ApiParam注解提供取值范围及含义说明。然而，当枚举类的值及含义变更时，修改所有涉及的接口上的Swagger描述信息成为繁琐工作，且容易遗漏。为了解决这个问题，可以自定义扩展Swagger的能力，实现接口文档根据枚举类动态更新描述信息。

首先，分析Swagger框架的处理逻辑，发现@ApiParam注解的内容会在生成文档时被显示。因此，可以通过自定义处理类实现接口逻辑的定制。同样地，可以找到处理@ApiImplicitParam和@ApiModelProperty的接口类，从而实现通用能力。

自定义注解实现基于枚举类生成描述，简化过程并提供统一的实现方式。例如，通过@ApiPropertyReference注解，指定字段名称、简要描述、是否必填以及对应的枚举类。对于枚举类，使用@SwaggerDisplayEnum注解指定用于Swagger注解中的字段映射。

利用反射技术获取枚举类中值与描述信息，将其拼接成所需内容。自定义扩展处理器，实现对API入参和数据实体类字段的取值说明自动生成。

运行程序后，效果显著。API接口中入参描述自动显示取值说明，并在界面中变为下拉框，确保输入允许的值。Model中的字段描述也自动带上枚举类定义的候选取值内容与说明。当枚举类内容变更时，Swagger接口文档描述内容实时同步更新。

通过自定义注解方式扩展Swagger的能力，简化了接口文档维护工作，提高了开发效率，确保了文档内容与实际代码处理情况的一致性。