mgmt+tsp, brownfield for vmware/avs

[weidongxu-microsoft]

vmware/avs already GAed with Swagger

service moved to TypeSpec on 2023-09-01
Azure/azure-rest-api-specs#28023
(at the time of the PR, the breaking changes CI having problem and not picking up the breaks)

service should name the folder as suffix ".Management", see https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md#service-folder-structure

One remaining issue on typespec-azure

• Singleton resource do not work with separate client namespace typespec-azure#1374

WIP

• modification to service sdk, tspconfig / client.tsp for vmware azure-rest-api-specs#29308
• test for Java test - mgmt, avs via tsp azure-sdk-for-java#40479
• test for Java (from Swagger) test, avs from swagger azure-sdk-for-java#40584

[weidongxu-microsoft]

REST API breaks

• removal of OperationProperties properties from Operation (include a type change on origin property) <- service want this change
• leaseTime changed from int64 to int32 <- fixed
• dnsServices changed from int64 to int32 <- fixed
• changes of "x-ms-mutability", e.g. properties in Addon changed to "read", "create" <- should have been fixed by the new typespec-azure-resource-manager (released Update TypeSpec to latest 2024-06 release - 0.57 & 0.43 azure-rest-api-specs#29440)

Need confirmation from service whether this is intended.

[weidongxu-microsoft]

API breaks

• extensible enum WorkloadNetworkName changed to default in URL
• ManagementCluster now does not extends CommonClusterProperties (this break is minor, and can be changed back to use model ManagementCluster extends CommonClusterProperties if necessary)

This is hard to keep non-breaking change in SDK.

• multiple places in PATCH, that previously request body is e.g. WorkloadNetworkSegment (same model as in PUT) being changed to WorkloadNetworkSegmentUpdate <- to be fixed via tsp, avs, remove Update model to keep consistency with stable Swagger azure-rest-api-specs#29392
• rename of List responses from ##List to ##ListResult <- to be fixed via tsp, avs, rename List API response schema back to ##List azure-rest-api-specs#29408

[weidongxu-microsoft]

SDK models

• x-ms-client-flatten
• mismatch on model names / property names

Mostly addressable in "client.tsp"
Azure/azure-rest-api-specs#29308

Important: AddonProperties cannot be x-ms-client-flatten as it is polymorphic
Should TCGC handle this (i.e., set flatten=false, whatever the @flattenProperty)?

[weidongxu-microsoft]

SDK operation groups

• Lots of @operationId, which is not supported in SDK emitter (they are only for typespec-autorest emitter)

WIP on whether we need to modify the interface structure in "route.tsp"
e.g. Azure/azure-rest-api-specs@7105e2d

(alternative is write all the APIs explicitly in client.tsp, which likely be hard to maintain)

[weidongxu-microsoft]

Potential bug

Java: seems missing Addon$Update.withProperties <-- not emitter bug, ARM ProxyResource has the @visibility("read", "create") https://github.com/Azure/typespec-azure/blob/main/packages/typespec-azure-resource-manager/lib/models.tsp#L54-L68

[cataggar]

service should name the folder as suffix ".Management", see https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md#service-folder-structure

I thought it was the RP name. Yes, you can change it to align with the guidance.

[cataggar]

• removal of OperationProperties properties from Operation

We do not actually want the operation API in our spec or SDKs. I've never understood why it is required. Anyhow, in TypeSpec we are using the standard typespec-azure-core definition.

https://github.com/Azure/azure-rest-api-specs/blob/32f566eb38af9593cfc1ed183362471c50d67fb2/specification/vmware/Microsoft.AVS/routes.tsp#L15

[cataggar]

• leaseTime changed from int64 to int32

This was unintentional. It should be changed back to int64.

[cataggar]

• extensible enum WorkloadNetworkName changed to default in URL

This was an approved breaking change. model WorkloadNetwork is a @singleton and this is how it is modeled in TypeSpec.

[cataggar]

• ManagementCluster now does not extends CommonClusterProperties (this break is minor, and can be changed back to use model ManagementCluster extends CommonClusterProperties if necessary)

The properties are spread in. This is how it is done in TypeSpec.

model ManagementCluster {
  ...CommonClusterProperties;
}
model ClusterProperties {
  ...CommonClusterProperties;
}

I'm not sure of another way to do it in TypeSpec. For example, this does not work here:

Not having the inheritance modeled is breaking, but seams acceptable.

[cataggar]

SDK operation groups

• Lots of @operationId, which is not supported in SDK emitter (they are only for typespec-autorest emitter)

WIP on whether we need to modify the interface structure in "route.tsp" e.g. Azure/azure-rest-api-specs@7105e2d

(alternative is write all the APIs explicitly in client.tsp, which likely be hard to maintain)

I did a lot of work to make the operationIds match in the generated OpenAPI. Are there operationIds that do not match? Are you generating the SDK from the OpenAPI spec or directly from TypeSpec?