Supporting $ref for paths

[paragon]

I'm attempting to migrate away from Redocly to zudoku, and seem to have encountered an issue using $ref in individual paths. I describe my issue below in what appears to be a bug, but please do let me know if I am making a simple mistake!

As seen at https://swagger.io/docs/specification/v3_0/using-ref/#considerations, it is valid syntax to have the following:

paths:
  /users:
    $ref: "../resources/users.yaml"
  /users/{userId}:
    $ref: "../resources/users-by-id.yaml"

To start, I created an example Project using:

npm create zudoku-app@latest

...with my project name being example.

As such, the generated file structure contains apis/openapi.yaml. Within api/, I created a folder called paths, with a file inside it called user.yaml, as such:

example
- apis/
--- openapi.yaml
--- paths/
----- user.yaml
<remaining generated files that are untouched>

To illustrate the issue I am encountering, I am using the simple example seen at https://swagger.io/docs/specification/v3_0/basic-structure/#_top. I would expect to see the /users path rendered when navigating to localhost:9000/api - however, I only see the Overview page (which shows Sample API and the description of Optional multiline or single-line description in CommonMark or HTML.).

Below are the relevant apis/openapi.yaml and apis/paths/user.yaml files generated from said example.

apis/openapi.yaml

openapi: 3.0.0
info:
  title: Sample API
  description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
  version: 0.1.9

servers:
  - url: http://api.example.com/v1
    description: Optional server description, e.g. Main (production) server
  - url: http://staging-api.example.com
    description: Optional server description, e.g. Internal staging server for testing

paths:
  /users:
    $ref: 'paths/user.yaml'

apis/paths/user.yaml

get:
  summary: Returns a list of users.
  description: Optional extended description in CommonMark or HTML.
  responses:
    "200": # status code
      description: A JSON array of user names
      content:
        application/json:
          schema:
            type: array
            items:
              type: string

[linear]

ZUP-4014 Supporting $ref for paths

[mosch]

Hey @paragon - today we don't support files in references. You can get things working by putting everything into one file.

Definitely a change we want to make soon, so we're happy to accept a PR for this.

[mosch]

Hey @paragon we made some changes that allows us to get this working soon. Are you still planning to migrate to Zudoku?

[paragon]

Hey @mosch - I sure am! I don't have the throughput to work on a PR currently, but we are still very interested in using Zudoku :-)

[mosch]

Awesome, we started working on it here: #578