Swagger/OpenAPI ResponseBodies Parameter with Slight Variances

Question

How can I change one part of the $ref, or add to it?

I have an OpenAPI 3.x response body:

ordernumber:
  $ref: '#/components/requestBodies/ordernumber'

The descriptive text is applicable to every instance I use this in, except for the last line. That changes for each product, like a product number.

There are similar questions but about schemas that don't seem to apply, neither do the anyof operators. I'd guess it should be like this, but of course, this doesn't work since no additional operation can be used with $ref.

ordernumber:
  $ref: '#/components/requestBodies/ordernumber'
  description: For all units number T100-T1200.

Related (or duplicate): [Schema properties ignored when using `$ref` - why?](https://stackoverflow.com/q/33629750/113116) — Helen, Feb 18 '21 at 19:32

score 1 · Accepted Answer · answered Feb 18 '21 at 19:31

1

this doesn't work since no additional operation can be used with $ref.

Your example will work in OpenAPI 3.1 (new version released on February 16, 2021). OAS 3.1 supports having a description alongside $ref. In case of non-schema $refs, the adjacent description is supposed to override the description defined in the referenced component (if any).

answered Feb 18 '21 at 19:31

Helen

87,344
17
243
314

Thanks. That was just lucky timing, it being added just two days before. – ForEachLoop Feb 20 '21 at 08:43

Swagger/OpenAPI ResponseBodies Parameter with Slight Variances

1 Answers1