OAS 3.1.0如何定义名称与值不一致的枚举以在构建中生成对应代码
解决方案
1. 解决IntelliJ const属性报错问题
const是OpenAPI 3.1版本才正式支持的特性,低于该版本的规范不允许使用该属性,你可以先确认两个配置:
- 你的OpenAPI声明头确实填写的是
openapi: 3.1.0,版本号没有写错 - 打开IntelliJ的
Settings > Languages & Frameworks > OpenAPI and Swagger,将当前项目的校验规范版本设置为3.1,IDE就不会再报const禁止的错误。你原本写的oneOf+const写法本身完全符合3.1规范,配置正确后可以正常使用:
openapi: 3.1.0 # ...其余配置 components: schemas: EnumType: oneOf: - title: TYPE_A const: 'Some text for type A' - title: TYPE_B const: 'Some text for type B' - title: TYPE_C const: 'Some text for type C'
2. 兼容全版本的通用实现方案
如果你的工具链(比如代码生成、网关校验等)还不支持OpenAPI 3.1,推荐使用扩展字段+枚举的通用方案,这也是行业内的普遍用法:
openapi: 3.0.0 # 兼容3.0及以上所有OpenAPI版本 # ...其余配置 components: schemas: EnumType: type: string # 这里写实际接口传输的枚举值 enum: - 'Some text for type A' - 'Some text for type B' - 'Some text for type C' description: | 枚举映射关系: - TYPE_A: Some text for type A - TYPE_B: Some text for type B - TYPE_C: Some text for type C # 自定义扩展字段,OpenAPI Generator等代码生成工具可原生识别,直接生成和Java示例一致的键值分离枚举类 x-enum-values: TYPE_A: 'Some text for type A' TYPE_B: 'Some text for type B' TYPE_C: 'Some text for type C'
x-开头的是OpenAPI规范明确允许的自定义扩展字段,所有OpenAPI工具都支持,不会触发校验错误。
内容的提问来源于stack exchange,提问作者gtludwig
相关产品推荐
相关产品推荐

