CODEWITHSUNDEEP
javajsonswaggerjsonschemaopenapi
James Hameson
James Hameson

Reputation: 341

Open Api $ref to use url

I have a problem to use open api v3 $ref to call a URL

I wrote an open api v3 specification to have documentation for a REST app. I am using $ref to validate the input parameters of this documentation. These $refs are pointing to an json schema in a url.

This is an example of the apen api documentation:

(doc.yml)

  /myapi:
      get:
        description: Some Description
        parameters:
          - name: profile
            in: query
            description: Some description
            required: false
            schema:
              $ref: 'http://localhost:8089/refs#/properties/profile'

The endpoint http://localhost:8089/refs#/properties/profile is returning 

        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "title": "Some Example",
        "definitions": {},
        "properties": {
            "profile": {
                "default": "",
                "examples": [
                    "1.0.0"
                ],
                "pattern": "^(\\d+\\.\\d+\\.\\d+)$",
                "type": "string",
                "title": "This is a version",
                "$id": "#/properties/profile"
            }
        },
        "$id": "myid1"
    }

I copy and pasted the doc.yml in the swagger and the input is validated and everything works perfect.

Due to changes in the endpoint (http://localhost:8089/refs)

I'm receiving this response:

  "oneOf": [
    {
      "$ref": "id1"
    }
  ],
  "$schema": "http://json-schema.org/draft-07/schema#",
  "description": "Some Description",
  "type": "object",
  "$id": "someid",
  "definitions": {
    "id1": {
      "description": "Some description",
      "additionalProperties": false,
      "type": "object",
      "title": "Some Example",
      "properties": {
        "profile": {
          "default": "",
          "examples": [
            "1.0.0"
          ],
          "pattern": "^(\\d+\\.\\d+\\.\\d+)$",
          "type": "string",
          "title": "The Version Schema",
          "$id": "#/properties/profile"
        }
      },
      "$id": "id1"
    }
  }
}

After this change, Swagger is throwing this error.

"Could not resolve pointer #/properties/profile"

My questions are. Is it possible to keep using the #/properties/profile as id when the schema is using oneOf? How can I make open api to validate the input if the json schema is using oneOf? Do I have to use another path rather that #/properties/profile?

Upvotes: 0

Views: 2505

Answers (1)

Jason Desrosiers
Jason Desrosiers

Reputation: 24399

Remember that Open API uses it's own flavor of JSON Schema. It leaves some things out, adds some things, and modifies somethings. Currently, Open API does not support $id/id (Reference: https://swagger.io/docs/specification/data-models/keywords/). The good news is that you weren't using $id in any meaningful way, so just leaving it out doesn't change your situation.

Your $ref: 'http://localhost:8089/refs#/properties/profile' doesn't work anymore because that path doesn't exist anymore. The structure of the document has changed, so the JSON Pointer fragment has to use the new structure. It would have to be $ref: 'http://localhost:8089/refs#/definitions/id1/properties/profile'

Upvotes: 1

Related Questions