Named enums in TypeSpec

[AnReZa]

We're using TypeSpec to define a web API. One of the requirements is to add a larger enum to that API. My first, naive approach was the following:

/**
 * Enumeration of all possible device types.
 */
enum DeviceType {
    /**
     * Unknown DeviceType
     * UNKNOWN_DEVICETYPE
     * */
    UnknownDeviceType: -1,

    /**
     * Some other device type
     * OTHER_DEVICETYPE
     */
    OtherDeviceType: 0,

    /**
     * Some fancy device type
     * FANCY_DEVICE
     */
    SomeFancyDeviceType: 1,
    ...
}

Now, this code translates into the following using tsp compile and java -jar openapi-generator-cli-7.8.0.jar generate:

DeviceType:
  type: number
  enum:
    - -1
    - 0
    - 1

This gets converted into the following c# class:

/// <summary>
/// Enumeration of all possible device types based on table `dbo.DeviceTypes`.
/// </summary>
/// <value>Enumeration of all possible device types based on table `dbo.DeviceTypes`.</value>
public enum DeviceType
{
        
    /// <summary>
    /// Enum _1Enum for -1
    /// </summary>
    [EnumMember(Value = "-1")]
     _1Enum = 1,

    /// <summary>
    /// Enum _0Enum for 0
    /// </summary>
    [EnumMember(Value = "0")]
    _0Enum = 2,

    /// <summary>
    /// Enum _1Enum2 for 1
    /// </summary>
    [EnumMember(Value = "1")]
    _1Enum2 = 3,
   ...
}

As you can see, no names, no comments, just some weird and useless randomly generated enum members with random numbers. Is there a way to use the generate a proper enum description with TypeSpec?

[allenjzhang]

@chrisradek, @wanlwanl, do we have an issue on this for openapi3 emitter?

[chrisradek]

I think this is a limitation of Open API 3.0. The enum field isn't allowed to contain any descriptions - you'd need to document all the enum values in the description of the schema containing the enum field.

For Open API 3.1, the spec does mention that you could generate an anyOf/oneOf of subschemas containing a const value, then use either the title or description field of the subschema to document the value. However the tools consuming this output would need to know to treat it as an enum instead of a union. We can create an issue to support generating output like this for Open API 3.1.

[AnReZa]

@chrisradek That sounds like a good approach. I think we agree that in the current state, the given definition does not really correspond to the result that comes out in the end. At least I would not expect [EnumMember(Value = "-1")] _1Enum = 1 from the definition UnknownDeviceType: -1.

[chrisradek]

Created an issue to track: #5721