Swaggers omit x-ms-enum which causes spurious diff's

[tombuildsstuff]

Unfortunately the Azure Swagger quality is pretty variable, and whilst the majority of constants use x-ms-enum, some others don't. This leads to weird naming in the SDK as we've raised previously such as Enum42 - which is an issue across the Azure SDK's.

As requested in Azure/azure-sdk-for-go#2182 - is there a plan to fix this data quality issue?

---

The original comment in Azure/azure-sdk-for-go#2182:

@RickWinter reading through the original comment this appears to be more regarding the Enums changing names across versions (than the validation mentioned in Joel's comment, where this got renamed) - for which the root-cause appears to be missing x-ms-enums in the Swaggers - whilst this could be fixed in this SDK, is there a plan to go through and add the missing x-ms-enums to the Swaggers, which would fix this?

Originally posted by @tombuildsstuff in Azure/azure-sdk-for-go#2182 (comment)

[jhendrixMSFT]

The problematic naming cited above is due to how the track 1 modeler works. This has been fixed in track 2.

Adding x-ms-enum at this point will introduce breaking changes in track 1 (albeit with improved names) and track 2 (different, though possibly improved) names.

[ghost]

Hi @tombuildsstuff. Thank you for opening this issue and giving us the opportunity to assist. We believe that this has been addressed. If you feel that further discussion is needed, please add a comment with the text “/unresolve” to remove the “issue-addressed” label and continue the conversation.

[ghost]

Hi @tombuildsstuff. Thank you for opening this issue and giving us the opportunity to assist. We believe that this has been addressed. If you feel that further discussion is needed, please add a comment with the text “/unresolve” to remove the “issue-addressed” label and continue the conversation.

[tombuildsstuff]

@jhendrixMSFT I get that's been fixed in Track2, but I was specifically wondering regarding the data quality issue rather than fixing this in the code generator - since that would also fix the larger issue with names such as OdataTypeBasicMetricAlertCriteriaOdataTypeMicrosoftAzureMonitorSingleResourceMultipleMetricCriteria too for downstream consumers too.

To be honest I think this is tooling missing from the azure-rest-api-specs repository - perhaps that'd be a worthwhile investment here, intentionally not being a part of autorest but instead just checking these singular items for speed purposes - but running that inside of a Github Action would solve this. Perhaps this'd make more sense on that repository in retrospect?

[jhendrixMSFT]

I believe there's been talk about adding a linter rule to enforce the inclusion of x-ms-enum on enum types. @nickzhums do you know anything about this?

[ghost]

Hi @tombuildsstuff, since you haven’t asked that we “/unresolve” the issue, we’ll close this out. If you believe further discussion is needed, please add a comment “/unresolve” to reopen the issue.

[tombuildsstuff]

/unresolve as this is still pending

[nickzhums]

@lirenhe this seems an engineering issue - could you help to investigate?

[tombuildsstuff]

@RickWinter to clarify - this issue isn't specifically regarding Track1 - Track2 merely works around it - this is a data issue which needs to be fixed within the Swagger itself. I'd suggest moving this issue to the Swagger repository but issues on that repository seem to be ignored.

Although a linting rule would go some way towards fixing this, since this is a soft-requirement it's possible for teams to ignore the linters which brings us back to where we are today - instead I'd argue that Enum Names should be explicitly defined by the Service Team to highlight their intention and as such should be a hard-requirement instead.

If these are pre-defined by the Service Team (and it's discouraged, but still possible to rename them across API versions) this would mean these are considered ahead of time - rather than changing as they do today (since at least in Track1 these can come from the Json Field Name in some cases).

Whilst that may seem like trivial difference, it puts the onus on the Service Team to give a canonical name to this Enums, which makes it less likely (but still possible) to change over time - meaning that users of the (any of the) Azure SDK's don't need to dig in and identify this themselves upon upgrading between different API versions.

Hopefully that helps clarify that a little further, but let me know if there's anything else :)