Swagger annotations $ref as string

[DanPottsHimself-Mkodo]

Describe the bug

When trying to use $ref to point to an external schema json, the definition is only returned as just "string". It's not able to resolve the path to the json it seems. 'Could not resolve reference: Tried to resolve a relative URL, without having a basePath.'

/**
 * @swagger
 * /api/example:
 *   get:
 *     description: Example description
 *     responses:
 *       200:
 *         description: Success
 *         content:
 *            application/json:
 *             schema:
 *               $ref: schemas.json#/definitions/AnExampleDefinition
 */

External schema:

{
    "$ref": "#/definitions/AnExampleDefinition",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "definitions": {
        "AnExampleDefinition": {
            "additionalProperties": false,
            "properties": {
                "isThisPossible": {
                    "type": "boolean"
                }
            },
            "required": ["isThisPossible"],
            "type": "object"
        }
    }
}

Any help appreciated

Reproduction

Complete

System Info

System:
    OS: macOS 12.5.1
    CPU: (8) arm64 Apple M1
    Memory: 1.84 GB / 16.00 GB
    Shell: 5.8.1 - /bin/zsh
  Binaries:
    Node: 16.19.0 - ~/.nvm/versions/node/v16.19.0/bin/node
    npm: 8.19.3 - ~/.nvm/versions/node/v16.19.0/bin/npm
  Browsers:
    Safari: 15.6.1

Used Package Manager

npm

Validations

• Follow our Code of Conduct
• Read the Contributing Guide.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A, please open a GitHub Discussion instead.
• The provided reproduction is a minimal reproducible of the bug.

[DanPottsHimself-Mkodo]

We do have a bit of a hacky workaround which is to convert our schema.json into a @Swagger annotation format programatically but not ideal that we are converting for it to be used