x-ms-enum extension always hides enum with a single value

In my service we have an API something like this: ApplicationPackage_Activate which has a parameter like this:

        "format": {
          "type": "string",
          "description": "The format of the application package binary file.",
          "enum": [
            "zip"
          ],
          "x-ms-enum": {
            "name": "ApplicationPackageFormat",
            "modelAsString": false
          }
        }

Our service API only supports a single value today – but we know in the future we will support more formats (that’s why we bothered to expose this property at all, if we thought it wasn’t going to change we would’ve just not exposed an enum in the REST API at all).

Yet, in AutoRest, an enum with a single value is not allowed. See ObjectBuilder.cs, specifically:

        private static bool IsSwaggerObjectConstant(SwaggerObject swaggerObject)
        {
            return (swaggerObject.Enum != null && swaggerObject.Enum.Count == 1 && swaggerObject.IsRequired);
        }

I see multiple good reasons to not hide the Enum even if it only has a single value:

1. It conveys meaning. Compare ApplicationPackage.Activate(foo, bar, baz, qux, PackageFormat.Zip) to ApplicationPackage.Activate(foo, bar, baz, qux). Yes, the second has 1 fewer argument, which is nice, but it also loses the extremely clear meaning that the package must be of the Zip format. We would be forced to document the limitation that only Zip is supported now in the description – which feels like we’re duplicating that information because we already said only Zip is supported in the Swagger specification when we defined the enum.
2. It protects us from future breaking changes (which is the whole reason we bothered to include the option in the REST API at all). It seems awkward that AutoRest forces our hand here – we might as well not have included the enum in the REST API.

It would be nice if AutoRest allowed us to either opt-in or opt-out of this behavior, maybe with a flag on x-ms-enum called squash-single-value-enums or something?

[matthchr]

@amarzavery Can you point me to where we msft says that adding a value to an enum is a breaking change? I tried to find somewhere that said that with respect to semver and couldn’t – I only saw an example about reordering enum integer values (i.e. Foo.A = 1 becomes Foo.A = 2).

Certainly, somebody could be broken if they wrote their code in such a way that they were not resilient to enum’s being added (i.e. they have no default case). But they could’ve also written their code in such a way that they are dependent on the number of methods or properties on a class (using reflection for example, as might be the case with some serialization schemes for example).

Does that make adding a new method a breaking change? (I could certainly craft code which would break if a new method was added) – I think the answer is no… yet there seems to me to be an isomorphism between that case and the enum case since both correctly work against the current structure defined in the API (this enum has 6 values and works, this class has 6 methods and works) and both break when the structure changes under them.

Moreover, is the enum thing a hard and fast rule? What about if the enum is only ever used as input and never returned from the service?

[pekspro]

I generated code with version 0.16.0.0 that is used by the latest version of Visual Studio. I was really confused why some properties in the generated classes was static. I spend quite some time to figure out was going on. For a long time, I thought it was some error in my definition.

That said, I think it’s appropriate to add some comments in the auto generated code explaining that enums with a single value is optimized.