Can we get x-ms-paths for operations that differ based on query param values?

[catalinaperalta]

I'm working on a spec that differentiates routes based on different query param values. In the old swagger world these operations would go under x-ms-paths. Is there a way to get these routes to be outputted with x-ms-paths in the generated openapi spec? Or is there another way to get the paths outputted?

This is also causing an issue because some of these paths are at the root of the server endpoint so the operations with specific query param values get generated with an empty path "" and the query params are completely lost. This causes various ci swagger checks to fail.

Example operation definition: https://github.com/Azure/azure-rest-api-specs/blob/3e047845933a1755cc8c40dea9fd2d0c54d403a9/specification/storage/Microsoft.BlobStorage/routes.tsp#L54-L60

The corresponding path definition: https://github.com/Azure/azure-rest-api-specs/blob/3e047845933a1755cc8c40dea9fd2d0c54d403a9/specification/storage/data-plane/Microsoft.BlobStorage/stable/2025-01-05/blob.json#L62-L63

[AlitzelMendez]

I talked with @catalinaperalta offline. She mentioned that this is a priority because the storage blob needs it to be able to release in the future. This is a complicated spec, so it is necessary to get the CI checks passing.

This can wait until after the GA date, but after that, it should be a priority. I will add the issue to the milestone that we will work on after the GA sprint.

[markcowl]

@AlitzelMendez @catalinaperalta Why is the OpenAPI output an issue in this case? Aren't we generating clients from tsp directly?

The OpenAPI3 library handles this by combining these shared-paths operations into a union of the types of each operation.

Is OpenAPI2 output required for generated API documentation, or some other required generated artifact?

[catalinaperalta]

@markcowl this is causing swagger validation checks to fail in ci in the azure-rest-api-specs repo. My original post was asking how I can make this work to get the generated openapi spec to output these routes with the specific query param values that I'm defining in the typespec. Storage defines different operations based on different query param values. Currently, if I define this the way they did in their original spec, the query params get swallowed and the path is empty causing many swagger validation issues. We dont even output a "/" instead of an empty path. Let me know how I can model this and get an openapi spec generated that doesnt cause issues with path validation. Additional context, I've tried hardcoding the query params in the set of params passed into the operation, I've also tried to leave the route with the expected query params but these routes keep getting outputted with an empty path value not even just the "/", I also tried using the @sharedRoute decorator without success. The result is that the expected query params are lost in the generated openapi spec. If you could provide an example of how this should be modeled and how the openapi should look that would be much appreciated.

Also seems like at minimum we should be generating these operations under the root path: "/"