How can I create OpenAPI spec files having $ref to other sub-files? Is this possible?

Question

I am unable to get OpenAPI spec Swagger "external refs" to work because Swagger rendering gives me an exception.

I must have this to make editing giant swagger documents more manageable since I don't have an auto-generator (due to architecture of azure sdk)

I am using 3.0.1 version, trying to do something like this:

paths:
  /v1:
    $ref: 'first-api.yaml#/paths/~1v1'
  /v2:
    $ref: 'second-api.yaml#/paths/~1v2'

The answer in this question doesn't work: How to use $ref to reference a path from another OpenAPI file?

The error I get looks like this (in IntelliJ-IDEA IDE using the OpenAI (Swagger) Editor plugin):

Would appreciate a link to an example project proving this works.

I tried it here, for example, and it fails:

• master json: https://www.npoint.io/docs/1409525a51f14540ab0a
• test1 json: https://www.npoint.io/docs/ae1d3959a91b828a3098
• test2 json: https://www.npoint.io/docs/775e7edb2c1ccb01a735

Answer 1

Try changing the $ref to specify the path starting with an explicit reference to the current directory. That is, prepend the path with ./

paths:
  /v1:
    $ref: './first-api.yaml#/paths/~1v1'

Answer 2

Change

  "paths": {
    "/test": {
      "$ref": "https://api.npoint.io/ae1d3959a91b828a3098#/paths/test"
    },
    "/document": {
      "$ref": "https://api.npoint.io/775e7edb2c1ccb01a735#/paths/document"
    }
  },

to

  "paths": {
    "/test": {
      "$ref": "https://api.npoint.io/ae1d3959a91b828a3098#/paths/~1test"
    },
    "/document": {
      "$ref": "https://api.npoint.io/775e7edb2c1ccb01a735#/paths/~1document"
    }
  },

Note the references look like ...#/paths/~1test and not ...#/paths/test. ~1 is the escape character used in path item references.

The fixed version is rendered correctly in Swagger Editor: