[enhancement] reuse response description

[ggirodda]

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.

[handrews]

@ggirodda I think you can just do

...
  responses:
    '200':
      $ref: '../index.yaml#/components/responses/200Ok'

allOf is 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 an allOf within the response schema instead.

[ggirodda]

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:

response:
  '200':
     description: Ok

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]

@ggirodda as you suspect, this is not currently possible up to OpenAPI 3.0.x (there is an issue for tracking the way swagger-ui allows allOf and 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 $ref property, and in the version of JSON Schema we use, the value of the $ref property is used to replace the containing object, but description is a string not an object. Also, there is no components/descriptions or components/strings container to reference into.

The overlay proposal (specifically that in OAI/Overlay-Specification#36) might well allow you to do this by specifying an update object with a JSON Path which matches all of the description properties in response objects where the key value is 200.

[darrelmiller]

I really wish Description wasn't required.

[handrews]

@webron @whitlockjc another $ref-with-stuff issue to add to that pile.

[handrews]

This is a subset of issue #2697, so I'm going to close it in favor of that issue (which has more discussion).