Inadequate Support for Security Schemes in TypeSpec

[mario-guerra]

Clear and concise description of the problem

Issue described by Chris Wood at Ozone API in this talk.

Description:

The "add auth" decorator in TypeSpec does not provide sufficient context for implementing standard OAuth flow objects. This limitation makes it challenging to generate complete and accurate Open API descriptions for security schemes. Specifically, the current implementation lacks the ability to fully describe the various OAuth flows and their associated parameters, such as authorization URLs, token URLs, and scopes.

As a result, additional manual steps are required to ensure the security objects are correctly implemented in the emitted Open API document. This often involves using overlays or other post-processing tools to add the necessary details, which can be cumbersome and error-prone.

Steps to Reproduce:

1. Define a security scheme using the "add auth" decorator in TypeSpec.
2. Emit the Open API document.
3. Observe that the emitted security scheme lacks complete information for OAuth flows.

Expected Behavior:
The "add auth" decorator should allow for the full specification of OAuth flow objects, including authorization URLs, token URLs, and scopes, resulting in a complete and accurate Open API description.

Actual Behavior:
The emitted Open API document contains incomplete security scheme information, requiring additional manual steps to correct.

Additional Context:
Improving the support for security schemes in TypeSpec would greatly enhance the usability and accuracy of the emitted Open API documents, reducing the need for manual post-processing and overlays.

Checklist

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.