$ref: not being followed

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

Hi bobfischer,

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

Cheers,

Frank

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