Separate annotation per enum value

[cowwoc]

Following up on swagger-api/swagger-core#1012 I'd like a service to return an Enum type and then document enum values by providing a separate annotation per value. I expect Swagger to aggregate these annotations so that all values and their descriptions are listed in the resulting documentation.

[bgrant0607]

+1. (Yes, github should have a voting button.)

[fehguy]

@cowwoc @bgrant0607 how would you propose this is represented in the description? For example, the current enum system uses primitive arrays:

myValue:
  properties:
    statusFields:
       type: string
       enum:
          - 1
          - 2

I suppose these could be objects, but we'll have to be prescriptive of the structure.

[cowwoc]

Each enum entry could be an object with name and documentation properties (or however you want to call it).

[henkosch]

+1

[jontejj]

@fehguy @cowwoc Or there could be a separate enumDescriptions array (keeping backwards compatibility) where the amount of descriptions should match the amount of enums. Perhaps it's not very pretty but it would be a way forward.

[drewish]

I would love to be able to use an object/hash for enums. For example I've got an app with credit card transactions that use rather cryptic values for the CVV checks. Here's what I'm forced to do to document it:

cvv_check:
  type: string
  title: CVV check
  description: |
    When processed, result from checking the CVV/CVC value on the transaction.

    * `D` - Suspicious transaction
    * `I` - Failed data validation check
    * `M` - Match
    * `N` - No Match
    * `P` - Not Processed
    * `S` - Should have been present
    * `U` - Issuer unable to process request
    * `X` - Card does not support verification
  enum:
    - D
    - I
    - M
    - N
    - P
    - S
    - U
    - X
  maxLength: 1

It would be much nicer to just have:

cvv_check:
  type: string
  title: CVV check
  description: When processed, result from checking the CVV/CVC value on the transaction.
  enum:
    D: Suspicious transaction
    I: Failed data validation check
    M: Match
    N: No Match
    P: Not Processed
    S: Should have been present
    U: Issuer unable to process request
    X: Card does not support verification
  maxLength: 1

Clients could either just use the keys and ignore the values, or show both in a <select> HTML element.

[ralfhandl]

+1

[webron]

I think there's a similar proposal for this for draft 5 of JSON Schema, will look for it.

[webron]

Parent issue: json-schema-org/json-schema-spec#579

[cabbonizio]

+1

[ePaul]

Currently the enum feature allows any kind of JSON thing in it – objects, arrays, strings, numbers, even mixed (though I'm not sure if things other than strings are supported by various toolings).

With the map variant proposed by @drewish we would be limited to strings. (This is not necessarily a problem for most cases, I just wanted to point it out.)

A more flexible version (though more verbose) would be to have an array of value/description pairs:

cvv_check:
  type: string
  title: CVV check
  description: When processed, result from checking the CVV/CVC value on the transaction.
  enum:
    - value: D
      description: Suspicious transaction
    - value: I
      description: Failed data validation check
    - value: M:
      description: Match
    - value: N
      description: No Match
    - value: P
      description: Not Processed
    - value: S
      description: Should have been present
    - value: U
      description: Issuer unable to process request
    - value: X
      description: Card does not support verification

I guess this corresponds to what @cowwoc proposed.