I am designing an API and I want to define an enum Severity which can have values LOW, MEDIUM or HIGH. Internally Severity gets stored as an integer so I want to map these to 2,1 and 0 respectively. Is there a way to do this in an OpenAPI definition? This is currently what I have for Severity:
severity:
type: string
enum:
- HIGH
- MEDIUM
- LOW
OpenAPI 3.1 uses the latest JSON Schema, and the recommended way to annotate individual enum values in JSON Schema is to use oneOf+const instead of enum. This way you can specify both custom names (title) and descriptions for enum values.
Severity:
type: integer
oneOf:
- title: HIGH
const: 2
description: An urgent problem
- title: MEDIUM
const: 1
- title: LOW
const: 0
description: Can wait forever
Note: This schema still uses 1, 2, 3 (i.e. the const values) as the enum values in the actual request/response payload, but code generators can use the title to assign custom names to those values in client/server code, for example:
# Python
class Severity(Enum):
HIGH = 2
MEDIUM = 1
LOW = 0
These versions do not have a way to define custom names for enum values, but some tools provide x- extensions for this purpose. For example:
OpenAPI Generator supports x-enum-varnames and x-enum-descriptions.
openapi-typescript-codegen and Scalar also support these extensions.
Severity:
type: integer
enum: [2, 1, 0]
x-enum-varnames:
- HIGH
- MEDIUM
- LOW
x-enum-descriptions:
- An urgent problem
- A medium-priority problem
- Can wait forever
NSwag supports x-enumNames:
Severity:
type: integer
enum: [2, 1, 0]
x-enumNames: [HIGH, MEDIUM, LOW]
Fern supports x-fern-enum
Speakeasy supports x-speakeasy-enums
APIMatic supports x-enum-elements
Check with your tooling vendors to see if they have a similar extension.
Open API 3.0
You can use description:
Severity:
type: integer
enum: [2, 1, 0]
description: >
dictionary:
* 2 HIGH
* 1 MEDIUM
* 0 LOW
It will not affect automatic code generation, but will be visible in generated documentation.
