Enum members numbers

[aleksei-saharov]

Hi all,

SUMMARY:

I want to define an enum with integer values and string descriptions, like

   Value1 = 0,
   Value2 = 3,
   Value4 = 4

The reason is that our API accepts integers, not strings, and we need to provide string description for these integers.

The issue is that Swagger Hub doesn't have a way to do it in a user-friendly manner.

The documentation gives us the following structure
YAML:

MyEnum:
  type: string
  enum: [
     Value1,
     Value2,
     Value4
  ]

But here enum members are strings, not integers.

There are several possible workarounds:

1. Use object description:
   YAML:

MyEnum:
  type: string
  description: |
      Value1 = 0

      Value2 = 3

      Value4 = 4
  enum: [
     Value1,
     Value2,
     Value4
  ]

But as we can see here issue 1108 Multiline in Description Not Rendering As Multiline.
However, the rendering looks ugly & not convenient at all for end users.

YAML:

MyEnum:
    type: integer
    enum:
      - value: 3
        description: Value 1
      - value: 10
        description: Value 2

BUT:
Rendering is ugly (see strings 0: object, 1:object):

Code generator return Internal Server Error (500)

I think that it represents information very well. But strings 0: object, 1:object not allow publish API spec.

None of these workarounds work well. Our company want to find best way to create enum with specified integer numbers as C# enum feature.
We do not interested in downloading and building GitHub code because we use SwaggerHub enterprise subscription. We want to have stable web client with nice rendered view and compilable generated code.

[webron]

@aleksei-saharov - took me a bit to process this, and I'm still not 100% sure what you're expecting here, so let's discuss.

Putting the spec aside, you're trying to describe an enum in your code, which is used in the API.
If I understand, you want a numeric-values enum, but would also like to provide, in the code, a description to those numbers.

The spec, today, does not support providing descriptions to enums. It's an existing limitation, one which does not change in the next version. The limitation is derived from the capabilities of JSON Schema.

The best way to describe enum values in the spec is indeed in the documentation. This, however, will not reflect back to the code.

The example you gave:

MyEnum:
    type: integer
    enum:
      - value: 3
        description: Value 1
      - value: 10
        description: Value 2

is technically a valid definition (enum values can be objects) but in terms of validation, nothing would validate against it - what you are effectively saying here is that MyEnum is both an integer and an object (the objects limited by the enum) and nothing will be both.

Given those limitations, you need to decide what you want to achieve, and hopefully I can guide you through it.

[aleksei-saharov]

@webron I understand that it is specification limitation but it will be nice to extend specification because many languages support integer values for enum members.

you're trying to describe an enum in your code, which is used in the API.

• correct

Our major interests:

1.

numeric-values enum

But NAMED numbers as we can see in different languages. I tell about possibility where you can difine numeric value for each named value in enum set.
I missed name in my previous example. It will be more correct:

MyEnum:
    type: integer
    enum:
      - value: 3
        name: Value1
        description: Value 1. Used for bla-bla-bla.
      - value: 10
        name: Value2
        description: Value 2. Used for bla-bla-bla.

2.

Stable code generation. As you can see in my first comment. Object enum members produce InternalServerError (500). It is very sad.
We plan to publish our specifications and client could generate client code and test sending requests to our API test server.
With current enum members structure it is impossible.

Our minor interest: support description for each enum member.

I hope you can help us to:

• find existing way to support it (if it exists);
• or tell if it could be supported later.

[webron]

Trust me, I'm well aware of the issue, and it's a common request.

When it comes to the spec itself, we've considered extending support for it in the next version, but eventually decided against it. The main issue is that this is just not how JSON Schema works and we have little control over JSON Schema. Going outside the bounds of JSON Schema (not by adding but by changing existing features) will cause any tool that does JSON Schema to break - less tooling support in general. We're not giving up on it, just don't have a solution yet.

As for extending our tools - we're committed to create tools that are compliant with the spec. That means that making changes that break compliance is not on our roadmap. However, we might consider adding non-breaking extensions at some point (we do something small like that in swagger-ui) but I cannot give you a timeline for it (nor a guarantee).