$ref: not being followed

[bobfischer]

I had a OpenAPI file I found unwieldy so decided to break it up. It seemed pretty straightforward, but when I launch the UI (http://localhost:3000/api-docs/) I get:

Speaker API
1.0.0
OAS 3.0
No operations defined in spec!

Here is the top level file:

openapi: 3.0.0

info:

title: Speaker API

version: 1.0.0

paths:

/reload-data:

$ref: './endpoints/reloadData.yaml'

/select-speaker/{name}:

$ref: './endpoints/selectSpeaker.yaml'

/speaker-status/{speakerName}:

$ref: './endpoints/speakerStatus.yaml'

/set-browser-source-url:

$ref: './endpoints/setBrowserSourceUrl.yaml'

/get-speaker-data:

$ref: './endpoints/getSpeakerData.yaml'

/get-current-speaker:

$ref: './endpoints/getCurrentSpeaker.yaml'

/set-speaker-data-file-path:

$ref: './endpoints/setSpeakerDataFilePath.yaml'

Any suggestion how to fix or debug what's going on?

Warm regards,

Bob

[frankkilcommins]

Hi @bobfischer,

Could you share some examples of the referenced files (e.g. reloadData.yaml and selectSpeaker.yaml)? 

Cheers,

Frank

[bobfischer]

Sure. Thank you. I had to get rid of the yaml extension due to a constraint on what files can be loaded here.

[frankkilcommins]

Hi @bobfischer,

When specifying the path reference, you have to use JSON Pointer notation to correctly reference the correct part of the file being referenced.

Here's an example of how we would do it in SwaggerHub, leveraging SwaggerHub domains to store the individual (or reusable) path item. See API example in SHUB:
https://app.swaggerhub.com/apis/frank-kilcommins/Path-References/0.0.1

If your using the open source editor or other tooling and wanting to use multi-file descriptions, you still need to provide the reference to the correct part of the file. I would also recommend keeping each file as a valid OpenAPI file.

So, here would be how I would specify the SelectSpeaker path item file:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Speakers API Fragment
paths:
  '/speakers/{name}':
    get:
      summary: Select a Speaker
      description: Get a speaker based on their name
      tags:
        - speakers
      parameters:
        - name: name
          in: path
          required: true
          description: Name of the speaker to be selected.
          schema:
            type: string
            maxLength: 100
            minLength: 1
            pattern: '^[a-zA-Z-\s]+$'
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    maxLength: 20
                    minLength: 1
                    example: success
                additionalProperties: false
        406:
          description: Not Acceptable
        429:
          description: Too Many Requests 

And then have the main OpenAPI description reference as follows:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Speakers API Fragment
paths:
  '/speakers/{name}':
    $ref: "https://raw.githubusercontent.com/frankkilcommins/OAS-Examples/main/OAS3_0/speakers-api-fragment.yaml#/paths/~1speakers~1{name}"

Above shows an absolute URL but you can reference relative files on the same host. The most important part is how I get to the pathitem in the file `#/paths/~speakers~1{name}`.

See https://swagger.io/docs/specification/using-ref/ for me info.

Hope this helps.

Cheers,

Frank