openapi-ts command fails when $ref points to non-schemas

[ehoodgoren]

Description

Our use case is using Redoc's codeSamples in our FastAPI, from which we generate a hey-api client. We're including code samples from external code files, which requires specifying $ref. However, when running openapi-ts - it crashes, probably because it tries to parse the example files, thinking they are schemas it should parse, even though it shouldn't care about it...

Here's the error:

The first argument must be of type string or an instance of Buffer, ArrayBuffer, or Array or an Array-like Object. Received undefined
TypeError: The first argument must be of type string or an instance of Buffer, ArrayBuffer, or Array or an Array-like Object. Received undefined
    at new NodeError (node:internal/errors:405:5)
    at Function.from (node:buffer:333:9)
    at Object.handler (<project_location>/node_modules/@hey-api/json-schema-ref-parser/dist/lib/resolvers/url.js:60:28)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)

Attached is a very minimal StackBlitz project that demonstrates this. I've recreated the issue with a basic express server that serves a static openapi.json file - which mimics the FastAPI behavior, with the same error. Start by running npm run api to run the express server, then run npm run openapi-ts to fetch the openapi.json from it and generate a client - and you'll get a crash and a log file with the error.

There's another error achievable - if there's no sample-codes (not having the directory, or not mounting it in the API) - running openapi-ts results in a crash where it tried to access the sample code. Again, it shouldn't care about it...

🔥 Unexpected error occurred. Log saved to /home/projects/hey-api-client-fetch-example-cfjyssvs/openapi-ts-error-1747212135509.log
🔥 Unexpected error occurred. Error opening file "/sample-codes/my_example.py" 
ENOENT: no such file or directory, open '/sample-codes/my_example.py'

Versions:

"@hey-api/openapi-ts": "^0.67.3",
"@hey-api/client-axios": "^0.7.0",

By the way, this only started happening after I upgraded @hey-api/openapi-ts from 0.53.1 to 0.67.3, it worked before upgrading

Reproducible example or configuration

https://stackblitz.com/edit/hey-api-client-fetch-example-cfjyssvs

OpenAPI specification (optional)

{
  "openapi": "3.1.0",
  "info": {
    "title": "FastAPI",
    "version": "0.1.0"
  },
  "paths": {
    "/my-route": {
      "post": {
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "Python",
            "label": "Python Example",
            "source": {
              "$ref": "/sample-codes/my_example.py"
            }
          }
        ]
      }
    }
  }
}

System information (optional)

No response

[bolt-new-by-stackblitz]

Start a new pull request in StackBlitz Codeflow.

• hey-api-client-fetch-example-cfjyssvs (Open reproduction)

[mrlubos]

Hey @ehoodgoren, only one question. How do you determine whether we shouldn't care about some $ref? I'm more surprised this used to not crash before!

[ehoodgoren]

Hey @mrlubos, thanks for the quick response!
You're right, I missed an important part - $ref can be used to point to other schema files, which does make distinguishing $refs we "care" about vs those we don't pretty difficult (or even impossible). So I take it back, sorry 😅

Here are some possible approaches for your consideration:

1. Gracefully ignore unresolved $refs (potentially with a warning message?)
2. Ignore $refs inside vendor extensions (like my example's x-codeSamples)
3. Only parse $ref from specific fields like responses, requestBody, etc