Add support for converting OpenAPI3 specs to TypeSpec

[chrisradek]

fix #3038
This PR updates the @typespec/openapi3 package to support converting OpenAPI3 specs to TypeSpec.

Example usage:

1. npm install @typespec/openapi3
2. npx openapi3-to-tsp compile --output-dir ./tsp-output /path/to/openapi-yaml-or-json

What's supported

• Parse OpenAPI3 specs in yml/json formats (via 3rd party package)
• Generates file namespace based on OpenAPI3 service name
• Populates @info decorator with OpenAPI3 service info
• Converts #/components/schemas into TypeSpec models/scalars.
• Converts #/components/parameters into TypeSpec models/model properties as appropriate.
• Generates a response model for every operation/statusCode/contentType combination.
• Operation tags
• Generates TypeSpec operations with routes/Http Method decorators
• Generates docs/extension decorators
• Most schema decorators
• Model inheritance via allOf
• Discriminators

What's not supported (yet)

• auth
• deprecated directive
• combining multiple versions of an OpenAPI3-defined service into a single TypeSpec project
• converting #/components/requestBodies and #/components/responses into models - TypeSpec doesn't seem to generate these and I didn't find examples in the wild where they were defined and actually used so deprioritized.
• emitting warnings/FIXMEs for unexpected/unsupported scenarios
• Probably a lot more that I'm still discovering

Notes

When going through the TypeSpec -> OpenAPI3 -> TypeSpec loop, the generated TypeSpec is going to be larger than the original. The biggest contribution towards this is because I'm currently generating a model for every possible response on every operation.

I can definitely pare this down with some simple heuristics that take into account what default statusCode/contentTypes are, and extract the referenced body type directly in the operation's return signature. I can also eliminate the @get decorators, @route("/") routes, and likely use some of the response models provided by TypeSpec.Http.

However - if I'm using this tool to convert from OpenAPI3 to TypeSpec - I thought it might be preferable to be more explicit in the generated output so there's no mystery on how things actually get defined. Will be interested in feedback on this.

Testing

For tests, I generate TypeSpec files for a number of OpenAPI3 specs. Most of the OpenAPI3 specs I generated from our TypeSpec samples packages. Then I'm able to compare the generated TypeSpec to the corresponding original TypeSpec file. I've also been diffing the OpenAPI3 specs generated from the original and generated TypeSpec files <- these are what typically show no changes outside of known unsupported conversions (e.g. auth).

[azure-sdk]

All changed packages have been documented.

• ✅ @typespec/openapi3

Show changes

@typespec/openapi3 - feature ✏️

Adds support for converting OpenAPI3 specs to TypeSpec via the new tsp-openapi3 CLI included in the @typespec/openapi3 package.

[azure-sdk]

You can try these changes at https://cadlplayground.z22.web.core.windows.net/prs/3663/

Check the website changes at https://tspwebsitepr.z22.web.core.windows.net/prs/3663/

[timotheeguerin]

Just a few more things,