Broken ref when using different file for request & response

Describe the bug

I have spent many hours trying to get to the bottom of this with no luck, so I’m hoping I’ve found a bug and it’s not just my ineptness! 😃

I have a very minimal schema representing get & post methods on a /queries endpoint (see schema below). I’m getting some super weird errors when trying to use them. The problem appears to be related to the post portion of the schema, which has references to two different files, one for the request object and one for the response object (although for debugging purposes, the contents of both files is currently identical)

When I make a GET request, I receive:

{
    "error": {
        "message": "can't resolve reference #/paths/~1queries/post/responses/201/content/application~1json/schema from id #",
        "missingRef": "#/paths/~1queries/post/responses/201/content/application~1json/schema",
        "missingSchema": ""
    },
    "message": "can't resolve reference #/paths/~1queries/post/responses/201/content/application~1json/schema from id #"
}

I am confident the referenced file schemas/queryresponse.yaml is present:

~/ems-api/api_spec$ find
./ems.yaml
./schemas/queryrequest.yaml
./schemas/queryresponse.yaml
./schemas/queries.yaml

In fact, the queries.yaml schema for the get route references this file with no problems.

Bizarrely, in the spec, if I rename the the ref for the response object to schemas/queryrequest.yaml, it works, which is especially odd since both files are currently identical.

I’m surmising from all this that it’s something to do with having two differently named files for request & response refs, though in the OpenAPI 3 spec I’ve not been able to find anything that would prohibit that.

I’m completely out of ideas. My spec seems valid (according to https://editor.swagger.io/ anyway). Might this be a bug?

Examples and context

ems.yaml:

openapi: 3.0.0
info:
  title: EMS
  description: Spec for EMS API
  version: 1.0.0
servers:
  - url: /api/v1.0
paths:
  /queries:
    get:
      summary: Returns all queries
      operationId: getQueries
      parameters:
        - name: offset
          in: query
          required: false
          description: The record index to start returning (e.g. 1 = second record)
          schema:
            type: integer
      responses:
        '200':
          description: An array of query objects
          content:
            'application/json':
              schema:
                $ref: 'schemas/queries.yaml'
        '500':
          description: Server error
    post:
      summary: Create a new query
      operationId: createQuery
      requestBody:
        description: A JSON object describing a query
        required: true
        content:
          'application/json':
            schema:
              $ref: 'schemas/queryrequest.yaml'
      responses:
        '201':
          description: The created query object
          content:
            'application/json':
              schema:
                $ref: 'schemas/queryresponse.yaml'
        '404':
          description: Query not found
        '500':
          description: Server error

schemas/queries.yaml:

type: array
items:
  $ref: 'queryresponse.yaml'

schemas/queryrequest.yaml & schemas/queryresponse.yaml:

type: object
properties:
  id:
    type: integer
    nullable: true
  title:
    type: string
  folder:
    type: string
    nullable: true

[AndrewIsh]

Hi @cdimascio

Thanks so much for responding to this so quickly. Your fix in v3.16.4 appears to work perfectly!

Thanks for creating such a useful library, it’s made life much easier for me on my project 😃

[AndrewIsh]

Hi @cdimascio

Thanks for the super speedy response. I just tried it and it works perfectly! Many thanks for fixing it, and for your continued work on this extremely useful package! 😃