R
Ryan Sondgeroth
Problem:
When exporting to OpenAPI, only the responses that are actively used in existing endpoints are included under components/responses. Additionally, the exporter automatically inlines response schemas in the path definitions, rather than keeping them as reusable references.
This limits the usefulness of the export for creating base API templates or boilerplate definitions, since many pre-built responses and standard components are excluded.
Proposed Enhancements:
  1. Option to include all pre-built components in export
• Add a setting that allows all pre-defined responses to be included in the components/responses section of the OpenAPI JSON/YAML export.
• This ensures consistency across projects and enables teams to build a “base API template” with shared assets, even if some responses aren’t currently tied to endpoints.
  1. Option to use $ref references in paths
• Add a setting to prevent automatic inlining of responses under paths.
• Instead, export them as $ref references to #/components/responses/....
Example:
"/provision": {
"post": {
"responses": {
"200": {
"$ref": "#/components/responses/OK"
},
"207": {
"$ref": "#/components/responses/MultiStatus"
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"422": {
"$ref": "#/components/responses/UnprocessableEntity"
}
}
}
}
Benefits:
• Enables the creation of reusable base API templates.
• Improves consistency across different projects.
• Makes the exported OpenAPI spec cleaner and more maintainable.
• Aligns with OpenAPI best practices by favoring $ref reuse instead of inlining.