Repository navigation
[enhancement] reuse response description #1741
Description
Hello,
First of all I want to thanks the openAPI community.
I really appreciate the standard, it really helps the communication between back and front developers. I tried to reuse response description in this way:
...
responses:
'200':
allOf:
- $ref: '../index.yaml#/components/responses/200Ok'
It seems that it's not a valid syntax even if it works well on swagger-ui
I think that it will be helpful to share the response description between different responses, avoiding to repeat the same message everytime.
Reacted by Serhii S.
Activity
handrews commentedon Nov 4, 2018
@ggirodda I think you can just do
allOfis a schema keyword and is only allowed in schemas. Usually it's the schema that you want to combine anyway, so if you need to add more schema constraints you can probably create a response that does that with anallOfwithin the response schema instead.ggirodda commentedon Nov 4, 2018
Thank you for your answer, I really had to explein it better, sorry. My problem is that every time I have a response, with 200 or 201 or other commons response code, I have to put the response description for each response, I just want the description to be shared between responses, because the content (the message) is always the same. I want to avoid to repeat every time this on my responses:
Because if one day I want to change the description of responses with code 200, I have to find and replace it on every file.
MikeRalphson commentedon Nov 5, 2018
@ggirodda as you suspect, this is not currently possible up to OpenAPI 3.0.x (there is an issue for tracking the way
swagger-uiallowsallOfand other schema-combining keywords outside of schema objects swagger-api/swagger-ui#4362).The major issue is that a Reference Object is just that, an object containing a
$refproperty, and in the version of JSON Schema we use, the value of the$refproperty is used to replace the containing object, butdescriptionis astringnot anobject. Also, there is nocomponents/descriptionsorcomponents/stringscontainer to reference into.The overlay proposal (specifically that in OAI/Overlay-Specification#36) might well allow you to do this by specifying an
updateobject with a JSON Path which matches all of thedescriptionproperties inresponseobjects where the key value is200.darrelmiller commentedon Nov 15, 2018
I really wish Description wasn't required.
handrews commentedon Feb 11, 2020
@webron @whitlockjc another
$ref-with-stuff issue to add to that pile.handrews commentedon May 25, 2024
This is a subset of issue #2697, so I'm going to close it in favor of that issue (which has more discussion).