Integer enum with named items

I would like to propose a new field called enumNames.

Example:

definitions:
  weather:
    type: object
    required:
      - type
    properties:
      type:
        type: integer
        format: int32
        enum:
          - 1
          - 2
          - 3
        enumNames:
          - Sunny
          - Cloudy
          - Rainy

This information is necessary for generating the following Java enum.

public enum Weather {
    Sunny(1),
    Cloudy(2),
    Rainy(3);

    private final int type;

    private Weather(final int type) {
        this.type = type;
    }

    public type getType() {
        return type;
    }
}

Some web APIs require clients to send/retrieve integer enum items while knowing what they mean. So it is useful to be able to generate this kind of enum.

I had been seeking advice in the following swagger-codegen issue, and got a conclusion that we need a vendor extension (which corresponds to this proposal) using Swagger 2.0 spec. https://github.com/swagger-api/swagger-codegen/issues/2690

[ralfhandl]

I like this, combined with json-schema-org/json-schema-spec#348:

type: integer
format: int32
enum:
 - value: 1
   name: Sunny
   description: Blue sky
 - value: 2
   name: Cloudy
   description: Slightly overcast
 - value: 3
   name: Rainy
   description: Take an umbrella with you

If the names should be unique (probably a prerequisite for code generation) a hashmap would be more appropriate:

type: integer
format: int32
enum:
  Sunny:
    value: 1
    description: Blue sky
  Cloudy:
    value: 2
    description: Slightly overcast
  Rainy:
    value: 3
    description: Take an umbrella with you

So enum could either have an array value with just the list of values, or an object value with named and potentially further annotated values.

[jmini]

With OpenAPI v3, some tools supports a x-enum-varnames extension to do so:

  weather:
    type: object
    properties:
      type:
        type: integer
        format: int32
        enum:
          - 1
          - 2
          - 3
        x-enum-varnames:
          - Sunny
          - Cloudy
          - Rainy

Other has started to use x-enum-values (see Extension Properties on OpenAPI Specs)