generate true enums if key-val description available

[sangecz]

for a given API method parameter:

...
{
  "name": "objectType",
  "in": "query",
  "description": "The object type Options: [0 = Undefined, 1 = Category, 2 = Article]",
  "required": true,
  "type": "integer",
  "format": "int32",
  "enum": [0, 1, 2]
},
...

instead of this output:

export type ObjectTypeTagsParamsEnum =
  '0' |
  '1' |
  '2'

it will create:

export enum ObjectTypeTagsParamsEnum {
  Undefined = '0',
  Category = '1',
  Article = '2',
}

This will give you convinient usage in eg. switch case where instead of:

case '1'

you can reference enum like that:

case ObjectTypeTagsParamsEnum.Category

[jnwltr]

Thanks, @sangecz. Do you consider this ...[key = value, ...] format in description field as something generic, or is that rather an ad hoc solution? I feel key-value enums should be modelled another way (although neither OpenAPI v3 addresses that).

In other words, why did you choose this solution?

[leiserfg]

I think that it's a ad-hoc solution, cause the swagger way of passing enums with names is by using thats names as value https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1

[sangecz]

@jnwltr I consider following format in description: ...[val = key, ...] because it's automatically generated from enum eg. (.NET):

public enum TagObjectType {
 Undefined = 0,
 Category = 1,
 Article = 2
}

maybe it's only .NET thing but the code also contents fallback to previous solution with type

@leiserfg that's true but not very usefull

[jnwltr]

Is that a stable/documented feature?

I fully acknowledge enum with named values is more self-explanatory than type composed of value strings. What I would on the other hand fear of, is relying on proprietary usage of description field.

Imagine a situation somebody else uses square brackets (I am not emphasising the fact the way you parse the string could be more robust) without intention to show key-value pairs. Then we would break the code (generate unusable type).

So I am afraid in case of the proposed solution:

• false negatives overrule false positives in their impact, and
• we would rely on a proprietary solution without any guarantee it would work this way in the future.

What do you think? Any other idea how to solve this, if you feel it's very beneficial?

[sangecz]

afaik, it's custom solution to generate enum description that way (our API team does that).

I don't see other way than more robust parser with fallback and to introduce this as possible feature of the generator.

If you want to close this PR for lack of standardisation of its feature, I totally understand, so go ahead :)

[jnwltr]

I was thinking of the following solutions:

• optional feature,
• generic plugin-like system, and
• customizable pre-processor combined with proprietary extension of the format

but do not think any of them is worth the effort for this feature. So let's abandon it for now as you propose, but we can keep it in mind, and come back to it once we have a better idea or situation changes.

Anyway, thanks a lot for this use case, proposal of its solution, and the follow-up discussion.