Forum Discussion

bobfischer's avatar
bobfischer
New Contributor
8 months ago

$ref: not being followed

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

3 Replies

  • 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