Stoplight Studio: $refs in the paths object not resolving

I’ve recently implemented a multi-file approach to authoring our OpenAPI specs, but I’m having a hard time getting Stoplight Studio to place nice with it. The issue seems to be related to my use of $ref within the paths section of my root openapi.yml file. This is what my paths object currently looks like:

    $ref: './paths/articles.yml'

And within articles.yml I have the following (truncated for the sake of brevity):

  operationId: get-article-by-slug
    - Articles
  summary: Get Article by Slug
  description: |-
    Returns data for a single `Article`
    - $ref: '../../common/components/parameters/path.yml#/brandPathParam'
    - $ref: '../../common/components/parameters/path.yml#/slugPathParam'
    - $ref: '../../common/components/parameters/path.yml#/experiencePathParam'
      $ref: '../components/responses/article200.yml'

AFAIK, this approach is valid, but Stoplight Studio does not seem to be able to resolve the reference to the path object. This is what it looks like:


As you can see, it knows nothing about the actual operation/parameters/responses contained in articles.yml

Is this a bug, or am I doing something wrong with the way I’m using $ref under the paths object? FWIW - when I export everything as a bundle, it all looks perfect and there are no issues resolving any references.

Any help would be greatly appreciated.

edit: fixing some formatting

1 Like

This is timely, I’m doing the same and came here to ask the exact same question. Spectral is very happy with the $ref as you describe but Studio just pretends there are no operations defined for the path.

Was hoping to have the API definition split across files per path to avoid merge hell when multiple teams and tech authors are working on the API at the same time. Interested to know how Stoplight best practises help here.

Thanks for sharing folks. How are you both using Studio: Web or Desktop? If desktop, which version?

We fixed this bug about a month ago, and we deploy pretty much daily to Studio Web so you should have noticed it working already.

If you’re using Studio Desktop, this fix will be released in v2. Our cadence of releases for Desktop has slowed down a little trying to get v2 right, but once it’s out you’ll be able to use path items behind a $ref (as I often like to do too).

Hi Phil! I am using Studio Web and am having a similar issue with the references. Except mine is showing the incorrect reference and is throwing studio for a loop. All of the underlying references seem to break and use the main reference. See the attached image. This also is similar to the post here Bug report: allOf not showing in published version