Question 339444 in Json Question posted in
Our archive of expertly curated questions and answers provides insights and solutions to common problems related to this popular data interchange format. From parsing and manipulating JSON data to integrating it with various programming languages and web services, our archive has got you covered. Start exploring today and take your JSON skills to the next level

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

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):

enter image description here

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

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

Tags:

2

Answers


  1. 0

    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:

    Login or Signup to reply.
  2. 0

    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'
    Login or Signup to reply.
Please signup or login to give your own answer.

Back To Top
Search