New enums or enum values in API break end user workflows

[cprivitere]

When new enum values are added to the upstream Equinix Metal API, they can cause issues with tooling that expects every enum to exist in the SDK.

We need to investigate how to more automatically add new enum values to the SDK.

[displague]

The generator offers an option that may be helpful here:
https://openapi-generator.tech/docs/generators/java/

Option	Description	Values	Default
enumUnknownDefaultCase	If the server adds new enum cases, that are unknown by an old spec/client, the client will fail to parse the network response.With this option enabled, each enum will have a new case, 'unknown_default_open_api', so that when the server sends an enum case that is not known by the client/spec, they can safely fallback to this case.	false No changes to the enum's are made, this is the default option. true With this option enabled, each enum will have a new case, 'unknown_default_open_api', so that when the enum case sent by the server is not known by the client/spec, can safely be decoded to this case.	false

[displague]

Semi-related, we can improve the documentation in the Java SDK for enums by taking advantage of x-enum-description:
OpenAPITools/openapi-generator#1693

Redocly will also take advantage of this in certain editions:
https://redocly.com/docs/api-reference-docs/specification-extensions/x-enum-descriptions

[displague]

Noting for search purposes that the status field enum value that triggered this discussion is delete_failed. https://deploy.equinix.com/developers/api/metal#tag/Interconnections/operation/getVirtualCircuit

[ctreatma]

The enumUnknownDefaultCase setting avoids validation errors but unfortunately it also obscures the actual value of the field (it comes back from the SDK as unknown_default_open_api instead of, e.g., delete_failed).

I chatted with some folks in the openapi-generator Slack and the consensus there was that plain strings should be used instead of enums (on response models, at least) because of this particular behavior. The downside of plain strings is that it can have a negative impact on rendered docs. That said, our own docs for findDeviceById provide a potential alternative: the state field on the 200 response has a very long description that covers the potential values of state and what they mean, so removing the enum from that field would not really negatively impact those docs.