Response Objects Rendered In-Line Instead of as References

[mario-guerra]

Clear and concise description of the problem

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

Description:

When emitting Open API documents using TypeSpec, response objects are rendered in-line with a reference object to the schema object that sits underneath them. This results in a more verbose Open API document than necessary. Ideally, response objects should be rendered as references rather than being declared in-line to maintain a cleaner and more maintainable document.

This issue leads to increased verbosity in the emitted Open API document, making it harder to read and maintain. A more streamlined approach within TypeSpec would greatly enhance the usability and cleanliness of the emitted Open API documents.

Steps to Reproduce:

1. Define multiple response objects in TypeSpec.
2. Emit the Open API document.
3. Inspect the emitted Open API document and observe that response objects are rendered in-line rather than as references.

Expected Behavior:
TypeSpec should render response objects as references to maintain a cleaner and more maintainable Open API document.

Actual Behavior:
The emitted Open API document contains response objects rendered in-line, leading to increased verbosity and reduced readability.

Additional Context:

• This issue has been encountered during the creation of open finance standards, where maintaining a clean and accurate Open API document is crucial.
• The verbosity of the emitted Open API document makes it harder to read and maintain, requiring additional manual steps to clean up the document.
• Automating the rendering of response objects as references within TypeSpec would significantly improve the workflow and reduce the need for manual intervention.

Improving TypeSpec to render response objects as references would reduce the verbosity of the emitted Open API documents and ensure cleaner, more maintainable documents.

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.