Swagger $ref gives "Could not resolve reference: undefined undefined"

Question

so I'm trying to separate the objects that we give in the responses body into separate yaml, or json, files and it gives all the time the same error.

Errors Resolver error at paths./api/thing.get.responses.200.content.application/json.schema.$ref Could not resolve reference: undefined undefined

This is my Main.yaml file:

openapi: 3.0.0
info:
 version: '0.0.1'
 title: 'thing-services'
 license:
   name: MIT
tags:
 - name: thingReturn
   description: ''
paths:
 /api/thing:
   get:
     tags:
       - thingReturn
     description: 'Recovers things'
     responses:
       '200':
         description: 'Returns a list of things.'
         content:
           application/json:
             schema:
               $ref: 'ThingList.yaml#/components/schemas/ThingList'
       '204':
         description: No Content. There was no content found.

This is my ThingList.yaml file:

components:
  schemas:
    ThingList:
      type: array
      items:
        $ref: 'Thing.yaml#/components/schemas/Thing'

This is my Thing.yaml file:

components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
        property1:
          type: integer
          format: int32
        property2:
          type: integer
          format: int32

Lets just say that everything is in the same folder (the original idea is to have the objects in a "object-schemas" folder), it doesn't work either. If I put the objects inside the Main.yaml file with the "#/components/schemas/...", it works fine but it beats the purpose of having everything organized in separate files. I don't know if I'm overlooking something. Any help is appreciated.

Where (in what tool) do you see the resolver error? In Swagger Editor (https://editor.swagger.io), for example, that would be expected because it [cannot handle](https://github.com/swagger-api/swagger-editor/issues/1409) relative file $refs like these. — Helen, Jul 14 '22 at 06:39

KarelHusa · Answer 1 · 2022-07-14T10:17:28.647

2

There seems to be a tiny typo.

In:

$ref: 'ThingList.yaml#components/schemas/ThingList'

is a missing slash, i.e. needs to be:

$ref: 'ThingList.yaml#/components/schemas/ThingList'

Also, make sure your referenced files are valid OpenAPI documents, e.g.:

openapi: 3.0.0
info:
  version: '0.0.1'
  title: 'thing'
  license:
    name: MIT

paths: {}

components:
  schemas:
    Thing:
      type: object
      properties:
        id:
          type: string
        property1:
          type: integer
          format: int32
        property2:
          type: integer
          format: int32

Then your OpenAPI files should fit together.

edited Jul 14 '22 at 10:17

answered Jul 14 '22 at 09:04

KarelHusa

1,995
18
26

shame on me for not seeing that, but no, sadly that didn't fix it. Still gives the "undefined undefined " – Bibily Bob Joe Jul 14 '22 at 09:58
I assumed your referenced YAMLs (Things.yaml, Thing.yaml) are just snippets, they need to be valid OpenAPI documents as well. – KarelHusa Jul 14 '22 at 10:14
Thanks for the correction, did it but still gives undefined. – Bibily Bob Joe Jul 14 '22 at 10:32
1

There must be another issue. I recommend using tools that help you to debug OpenAPI; I prefer IDEA with the OpenAPI plugin. – KarelHusa Jul 14 '22 at 10:35
Thx for the plugin. Didn't knew about it. Just tested the local preview and it works fine, but when I upload the Main.yaml to the test environment it still gives the undifined error, so yeah, it must be something else. – Bibily Bob Joe Jul 14 '22 at 10:57

Bibily Bob Joe · Accepted Answer · 2022-07-19T10:36:38.247

So, after trying and talking to my co-workers, we though that the problem was surrounding the relative path, which it was. We had to write the $ref regarding the repository's path it was going to, and it worked! :D

What really gave the hint was the console of the browser. It gave a 404 error and when clicking the url it was trying to go to, it gave a {"error":"404 Not Found"}, and we could see the url it was trying to go to, which was wrong regarding the repository we are working on.

EDIT: this works if the MainFile.yml is in the same folder as the objects that file is using. Like this:

$ref: ../objectList.yml/raw?ref=branchName#/components/schemas/object

Still trying to figure out how to get into a folder that should contain all the objects we are using. We tried writing in the $ref, but still gives the 404:

$ref: ../folderOfObjects/objectList.yml/raw?ref=branchName#/components/schemas/object

2nd Edit: so after talking to my senior, it was a thing of encoding the "/" in reference of the gitlab api:

$ref: ..repository/files/folderOfObjects%2FobjectList.yml/raw?ref=branchName#/components/schemas/object

The part of the url after "files/" and before "/raw/, if there are any "/", they should be "%2F".

This post gave it away: GitLab API - Unable to access file which is within a directory

Swagger $ref gives "Could not resolve reference: undefined undefined"

2 Answers2