Need $ref as a variable in open-api-spec.yml file

Open Source Swagger OS
, , , ,
1

Originally posted by Prasanna_Ailuri on November 15, 2022

Hi Team,

I am using Open-API-SPEC 3.0 and have a requirement to build the below mentioned object

{

“value”: “a12345”,

“$ref”: “https://example.com/v3/Resources/a12345”,

“display”: “Resource-a12345”

}

And when I specify the same in open-api-spec.yaml as below:

MyObject:  required:    - value  type: object  properties:    value:      type: string    display:      type: string    $ref:      type: string

I am receiving a wrong structure with 2 values in place of $ref, Could anyone suggest or guide me on how to solve my specific requirement?

Thanks in Advance,

Prasanna Ailuri

2

Originally posted by frankkilcommins on November 15, 2022

Hi Prasanna_Ailuri

Could you share your OpenAPI 3.0 definition? I’m not sure based on above what you are trying to achieve.

Thanks,

Frank

3

Originally posted by Prasanna_Ailuri on November 15, 2022

Hi frankkilcommins ,

We have an endpoint which returns objects as an array of below mentioned JSON:

{

“value”: “a12345”,

“$ref”: “https://example.com/v3/Resources/a12345”,

“display”: “Resource-a12345”

}

Thanks,

Prasanna

4

Originally posted by Prasanna_Ailuri on November 15, 2022

paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in CommonMark or HTML.
responses:
‘200’: # status code
description: A JSON array of user names
content:
application/json:
schema:
type: array
items:
$ref: ‘#/components/schemas/Response’
components:
schemas:
Response:
type: object
properties:
id:
type: string
meta:
type: array
items:
$ref: ‘#/components/schemas/Metadata’
Metadata:
required:

  • value
    type: object
    properties:
    value:
    type: string
    display:
    type: string
    $ref:
    type: string
5

Originally posted by frankkilcommins on November 15, 2022

Hi Prasanna_Ailuri

Thanks for the info. I’m still not 100% clear on what you are trying to achieve.

I’ve defined a version of an API with the path and schemas you have descripted at https://app.swaggerhub.com/apis/frank-kilcommins/UsersReference/1.0.0#/default/get_users

A sample response for the API would be as follows:

[
  {
    "id": "string",
    "meta": [
      {
        "value": "string",
        "display": "string",
        "$ref": "string"
      }
    ]
  }
]

Note that $ref in a JSON payload response has no semantic meaning. I think you might be misinterpreting how to use references in your API definition. The way you have defined it means that it’s just a string property with a name of "$ref". Using a JSON Schema keyword in this way may cause you issues in other tooling.

To be strictly compliant with OpenAPI 3.x, a JSON Reference can only be used where explicitly noted in the OpenAPI specification. For example, it can be used for Paths, Parameters, Schema Objects and more. Basically, if you can define a schema object inline then you can also put in a reference object.

You have defined your ‘MetaData Object’ as follows:

Metadata:
 required:
 - value
 type: object
 properties:
  value:
   type: string
  display:
   type: string
  $ref:
   type: string

The above usage is not using the $ref keyword as expected. To use references appropriately, the value of the $refkeyword must be a string representing an URI, URI reference, URI template or a JSON pointer.

For more information on how to use object references, see https://swagger.io/docs/specification/using-ref/

6

Originally posted by Prasanna_Ailuri on November 15, 2022

Hi frankkilcommins

Thanks for the detailing ,https://app.swaggerhub.com/apis/frank-kilcommins/UsersReference/1.0.0#/default/get_users is my exact requirement.

But when you build that object and return the response of it via any endpoint in Java

The below is happening:

[{
    "id": "string",              "meta": [{
        "value": "string",               "display": "string",                   "$Ref": "string",                         "$ref": "string"
      }]
  }]

An Extra Ref is getting added runtime

Thanks,

Prasanna

7

Originally posted by frankkilcommins on November 16, 2022

Hi Prasanna_Ailuri

Are you using Swagger-Codegen to generate your server implementation?

I’ve just generated a Java SpringBoot server stub from the OpenAPI definition shared above and the response from the GET ‘/users’ is as follows (which looks correct):

[
    {
        "meta": [
            {
                "display": "display",
                "value": "value",
                "$ref": "$ref"
            },
            {
                "display": "display",
                "value": "value",
                "$ref": "$ref"
            }
        ],
        "id": "id"
    },
    {
        "meta": [
            {
                "display": "display",
                "value": "value",
                "$ref": "$ref"
            },
            {
                "display": "display",
                "value": "value",
                "$ref": "$ref"
            }
        ],
        "id": "id"
    }
]

I suspect your issue is related to the usage of the keyword $ref. I would recommend that you change the name of that property so that it does not clash with a JSON Schema keyword.

Thanks,

Frank