Forum Discussion

Prasanna_Ailuri's avatar
Prasanna_Ailuri
New Contributor
3 years ago

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

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
      • Prasanna_Ailuri's avatar
        Prasanna_Ailuri
        New Contributor

        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

  • 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 $ref keyword 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/

  • 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