java枚举类在swagger中默认不显示具体值，需用@schema注解的allowablevalues显式列出常量名（如{"admin","user","guest"}），并在字段或参数上标注以展示可选值，配合@schema description和@jsonvalue可增强文档可读性。
Java 枚举类在 Swagger（如 Springdoc OpenAPI）中默认只显示类型名（如 Role），不会自动列出具体枚举值。要让 API 文档清晰展示可选值，需配合注解和配置主动“告诉” Swagger 枚举的含义。
使用 @Schema 注解声明枚举含义
在枚举类或字段上添加 @Schema，并通过 description 或 example 补充说明；更关键的是用 allowableValues 显式列出枚举常量名（字符串形式）：
- 适用于 Springdoc OpenAPI 1.6+（
springdoc-openapi-ui） -
allowableValues值为字符串数组，对应枚举常量名（不是实际值，除非重写了toString()或name()） - 例如：
@Schema(allowableValues = {"ADMIN", "USER", "GUEST"})
为枚举字段添加 @Parameter 或 @Schema
在 Controller 方法参数（如 @RequestParam、@PathVariable）或 DTO 字段上标注，确保 Swagger 解析到枚举约束：
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
- 查询参数示例：
@Parameter(allowableValues = "ADMIN,USER,GUEST") @RequestParam Role role
- Dubbo 或 DTO 字段示例：
@Schema(description = "用户角色", allowableValues = {"ADMIN", "USER", "GUEST"}) private Role role;
增强可读性：重写 toString() + 使用 @JsonValue
若枚举有业务含义的描述（如 ADMIN("管理员")），建议搭配 @JsonValue 和 toString()，再配合 @Schema 的 description 引导前端理解：
- 定义枚举时标注
@JsonValue在返回描述的方法上（通常为getDesc()或toString()） - Swagger 默认仍按
name()展示，但文档中可通过description补充说明：“取值：ADMIN（管理员）、USER（普通用户）…” - 这样既保持 JSON 序列化语义清晰，又让文档更易懂
全局配置（可选）：自定义枚举解析器
如果项目中大量使用枚举，且希望统一处理（如自动提取 getDesc() 作为文档说明），可编写 OpenApiCustomizer 或 ModelConverter 扩展，但对多数项目属于过度设计。优先推荐前三种轻量方式。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
