Unable to override descriptions for $ref'd query parameters

Originally posted by user heymcgovern to the Stoplight Community on 12/19/2022 at 04:47 ET.

Hey all 👋  I'm using Stoplight to design and document an API. The OAS (3.1) file was huge, so I've been working through it to abstract shared data into separate models. So far, so good -- the file is much smaller and way easier to maintain. Stoplight makes it easy to work with $refs 😄 

I've come up against a problem with query parameters.

We have some query parameters that are shared across endpoints. I'd like to override the description for some of these in the OAS file, which I've done before in other tools and I believe is a feature of 3.1. 

For example: for search, I'd like set the description include information about the scope of the search in some cases:

parameters:
  - $ref: ./parameters/query/search.yaml
    description: 'Return entities that match a search query. Searches `id` and `name`.

I can't seem to get Stoplight to support this reliably. In some cases I can override descriptions, in other cases I can't. Screenshot is a great example. I can override the last parameter, but Stoplight ignores the others. 

There are no differences in the $ref'd yaml files, other than the title and description. They have all of the same properties in the same order. I've not come up against this issue when overriding descriptions of models.

Is anyone able to help here? I found a known issue[1] that sounds similar, but it mentions duplication so I'm not sure it applies to me. If this is the same issue, does anyone have an ETA on a fix?

Thanks! 🎄 

https://support.stoplight.io/s/article/ref-description-overrides-are-duplicating-instead-of-respecting-description-text