How to define enum mapping in OpenAPI?

Question

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

Answer 1

OpenAPI 3.1

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

OpenAPI 3.0 and 2.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:

• AutoRest supports x-ms-enum.

• NSwag supports x-enumNames:

  Severity:
    type: integer
    enum: [2, 1, 0]
    x-enumNames: [HIGH, MEDIUM, LOW]
  

• openapi-typescript-codegen supports x-enum-varnames:

  Severity:
    type: integer
    enum: [2, 1, 0]
    x-enum-varnames: [HIGH, MEDIUM, LOW]
  

Check with your tooling vendors to see if they have a similar extension.

Answer 2

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.