Description for enum values

[n0tel]

I propose to add description for enum values. Like this

/installer:
  get:
    queryParameters:
      platform:
        enum:
          - ios
             description: Only for mobile device  // didn't work
          - mac
             description: Macintosh pc 
          - unix
             description: Any unix-like system

Now we can describe it in description like this:

/installer:
  get:
    description: |
      ios - Only for mobile device
      mac - Macintosh pc 
      unix - Any unix-like system
    queryParameters:
      platform:
        enum:
          - ios
          - mac
          - unix

but the first version seems more specific. What do you think of it?

[hwellmann]

I think the model of enum should be changed not to take a list of strings, but a list of objects, which would allow for name, description and any annotation references.

A flat list of strings is not rich enough for code or documentation generators, e.g. think of Java enums with additional arguments and Javadoc for each constant.

At the moment, I'm using the following workaround:

annotationTypes:
  enum:
    properties:
      values: _EnumValue[]
types:
  _EnumValue:
    properties:
      name: string
      description: string
  Colour:
    type: string
    (enum):
      values:
        - name: lightBlue
          description: Colour of the sky
        - name: red
          description: Colour of tomatos

Incidentally, this raises the question whether an annotation type (enum) may reference a non-annotation complex type (_EnumValue[]), or whether this is just a specification gap that happens to be supported by raml-parser-2.

I think it would be cleaner to reference another annotation type (like nested annotations in Java), but this does not seem to be possible.