search

Azure / typespec-azure

About TypeSpec Azure Libraries
https://azure.github.io/typespec-azure/
MIT License
14 stars 40 forks source link

RestAPI doc is still using operationId and we do not have a solid way to guarantee they are the same #1701

Open ArcturusZhang opened 2 days ago

ArcturusZhang commented 2 days ago

The docs team is using operationId to identify operations, and they decided to stick with swaggers. The downstream SDK generators (at least dotnet SDK) want to provide extra information that our user could use to look up through the REST API docs. The solution that dotnet SDK provides is to write the operationId into xml docs. TCGC did not pass through this operationId, therefore the downstream SDK generators need a concrete operationId instead of constructing an operationId again. But because of the existence of various name changing decorators, it is impossible for the SDK generators to calculate a correct operationId. Similar reason that TCGC and the autorest emitter that emits the swagger calculates the operationId independently, therefore I think it is also problematic in this solution, because in independent calculation, there is no guarantee that they always get the same result which leads to an operationId in swagger to mismatch the operationIds in SDKs.

So either, we could convince docs team to use a different identifier for operations so that we could use in the downstream SDK generators. Or TCGC and autorest could share a piece of code to calculate the operationIds and pass through this to SDK generators to guarantee the operationId for the same operation is always the same.

allenjzhang commented 2 days ago

Having different operation_id is definitely not ideal. As autorest depends on TCGC, it may make sense to have TCGC to expose operation_id and let autorest uses that.

There is still a risk that TCGC one differs from what autorest was generating, but we can run against spec repo to see the diff and correct the logic to be consistent.