Generate a tsp-location file as part of the openapi generation step

weshaggard commented 7 months ago

There is a need for various tools and validation steps to map back from a generated openapi document to the typespec that generated it. I would like to propose we generate a metadata file similar to what the sdk languages do with a tsp-location file (i.e. https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/openai/Azure.AI.OpenAI/tsp-location.yaml) that will contain a relative path to the TypeSpec that generated it.

This will enable us to give better errors from our validation tooling as well as to allow us to correlate an openapi APIView with its TypeSpec APIView.

I would suggest we do this for both the typespec-autorest and typespec-openapi3 emitters.

timotheeguerin commented 7 months ago

I think this is a subset of adding a sourcemap file for openapi3 and autorest emitter. In the case of autorest we could do something that just unblock the spec repo quickly but for openapi3 that file format we should be sure will provide the all sourcemap ability we want(or at least those can be added later).

e.g. I think a format that might be good is

source: ../main.tsp
mappings:
   "#/definitions/Foo": "Microsoft.Azure.MyService.Foo";
   "#/paths/xyz/get": "Microsoft.Azure.MyService.myOperation";

though here we probably also want a location of where Foo and myOperation are defined without having to recompile

weshaggard commented 7 months ago

Yes I do agree this could be part of the source map file.

Azure / typespec-azure

Generate a tsp-location file as part of the openapi generation step #193