Decide on representation of enum values in OpenAPI3

[markcowl]

We should be crisp about the meaning of enums in Cadl in general:

• enum is a fixed set of values that can be updated in a new api-version
• We may need additional patterns for
  • enums that will never add values
    • is this really a pattern?
  • enums that may add values without changing api-version
    • can this be represented using example values?
• Decide on how enums should be represented in OpenAPI3
  • Should we bring over any part of x-ms-enum?

[mikekistler]

I don't mind deferring the work to document how @knownValues is used by the OpenAPI emitter if this design issue is taken up quickly. But if this design discussion does not happen until March (as the milestone seems to indicate), that means that our documentation is incomplete / incorrect for at least 3 months, and that seems too long to me. Can we move up the date for this design discussion to at least Feb (i.e. we'd discuss in a design meeting in January)? If that's not possible, then I think we should either document the current behavior or remove it so that our docs accurately reflect the behavior of the code.

[stefan-schweiger]

Just to have it here as well for better visibility for this discussion

#189 (comment)

It's kind of hard to follow all the discussion around the topic of extensible enums. What would actually be generated for those extensible properties? I've seen mentioned a few times the x-ms-enum pattern or using anyOf.

For example there is the "zalando" way of doing it like this, which is what I would like to do:

DeliveryMethod:
  type: string
  x-extensible-enum:
    - Parcel
    - Letter
    - Email

There is an ongoing discussion in the OpenAPI specification about this topic. Maybe some comments in there could be a good inspiration for what people are currently using to define extensible enums, and it would be great if at least a few of the more common ones could be achieved with cadl.

OAI/OpenAPI-Specification#1552

[mikekistler]

This is resolved. The openapi3 emitter generates enums and unions of string values as enum.

[stefan-schweiger]

@mikekistler how would one generate one of the alternative extensible formats? write a custom emitter?

[mikekistler]

I don't think you need a custom emitter -- you can just add the extension by hand.

Playground example