Can we refer json from other file in the openapi json file ?

[mdhvcgf]

Hi, I’m trying to split my large openapi.json into smaller files and reference them with $ref. In my main spec I have:

"/ai/v1/lesson-plan/get-additional-blocks": { "$ref": "paths/lesson-plan/get-additional-blocks.json#/GET_METHOD" }

However, when I run validation I get an error. Is this the correct way to reference an external path definition in Swagger/OpenAPI? I saw this syntax in the documentation of Swagger but can’t get it to validate—what am I doing wrong? Below is my file structure

[helene-spring]

I banged my head on a wall trying to figure this out. If you dig through the mintlify prebuild code in your own installation, you will find out that OpenAPI parsing in Mintlify doesn’t automatically resolve external files $refs. Only remote URLs are considered “allowed” for the prebuild step. Local file $refs like paths/lesson-plan/get-additional-blocks.json are ignored and the spec that contains them are not registered in openApiFiles. When generateOpenApiFromDocsConfig tries to find your OpenAPI in openApiFiles, it fails.

So you either have to use a remote url and use that in the $ref (so your file has to be hosted somewhere already), or for now my solution is to incorporate the relevant part of the external file into the openapi spec. would be great to have a better solution for this, perhaps worth opening an issue about this.