Swagger-editor: add more field for $ref property

[monday0rsunday]

I defined some models, referencing other model, below is an example
‍‍‍

"Comment": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string"
                },
                "content": {
                    "type": "string"
                },
                "from": {
                    "description": "User created comment",
                    "$ref": "#/definitions/User"
                }
            }
}

but Swagger Editor warning me that

Swagger Warning
Extra JSON Reference properties will be ignored: description
Jump to line 77
Details
Object
code: "EXTRA_REFERENCE_PROPERTIES"
message: "Extra JSON Reference properties will be ignored: description"
path: Array [4]
0: "definitions"
1: "Post"
2: "properties"
3: "from"
level: 500
type: "Swagger Warning"
description: "Extra JSON Reference properties will be ignored: description"
lineNumber: 77`

I think that external definition having some fields like "description" would be accepted.

[saharj]

I tried the code and everything looks fine.

Am I missing something?

[saharj]

Ok, I figured out what the problem is. When you are using a $ref, it should'n have a sibling, otherwise you'll get a warning (it's weird that I didn't!). That's because when there is a $ref, everything (including $ref itself) will be replaced with the result of what that $ref is pointing to. So if you put siblings next to a $ref, they will not appear because resolver replaces it.

[AviiNL]

Is there any intention in the (near) future to get the above example to work? eg. to merge instead of replace with $ref? (or only replace the $ref object itself with the contents of $ref)

[webron]

@AviiNL - not quite up to use. We're using JSON references as defined by the JSON Reference spec which just doesn't allow what you describe.

[peacemakr]

then, whats the best way to include definitions defined elsewhere that have one ore more properties that are different?

[webron]

@peacemakr there's no 'best' way. You'd need to tailor and construct your models properly using composition.

[peacemakr]

I just looked at composition but don't think that'd help me (or correct me if I'm wrong). I've simplified the issue that I am facing.

parameters:
  UserId:
    name: user_id
    in: query
    description: User ID
    required: false
    allowEmptyValue: false
    type: integer
    format: int64
    minimum: 1

I have a UserID parameter that in some cases is required(required: true) and optional in others (required: false).
Now, I do not wish to copy and paste the rest of properties/attributes. Instead, I'd like to just refer to the base UserId definition/parameter and include the changes (ie. required:true). Something like below:

  UserIdStrict:
    $ref: '#/parameters/UserId'
    required: true

However, I get a warning "Extra JSON Reference properties will be ignored: required".

Any ideas how I could resolve this efficiently?

[webron]

That's a parameter, not a property. The only thing you can do is define two parameters, one required and one not, and refer to each where appropriate. There's no other alternative.

[peacemakr]

I was actually referring to "required", "type" etc as property/attribute of a parameter definition.

Copying the whole def for a small difference would leave a lot of duplicates );

[webron]

'properties' is a common term for model definitions, that's where the confusion was from.

Unfortunately, there's no way around it.

[AlwaysAbhl001]

@webron

 "definitions": {
      "UpdatedOrders": {
            "type": "object",
            "properties": {
                "OrderId": { 
                    "type": "integer" 
                },
                "Quantity": {
                    "type": "integer"
                }
            },
            "required": [
                "OrderId"
            ]
        },
      "Orders": {
           "$ref": "#/definitions/Pager",
            Properties:
                "ProductName": {
                    "type": "string"
                },
                "Quantity": {
                    "type": "integer"
                }
            }
        }
}

After "ref" I want to add extra properties as shown above. how could we make out this, Is there any workarounds for it?

[webron]

@AlwaysAbhl001 yes, use the allOf construct.

[AlwaysAbhl001]

@webron

"Orders": {
           "type": "object",
           "properties": {
           "allOf":{
           "$ref": "#/definitions/UpdateOrders",
            },
             "ProductName": {
                  "type": "string"
                }
            }

output:

"Orders": {
      "allOf": {
        "OrderId": integer,
        "Quantity": integer,
      },
      "ProductName": "string"
    }

But what we need

"Orders": {
        "OrderId": integer,
        "Quantity": integer,
         "ProductName": "string"
    }

Is there any probability for our expected one?

[webron]

"Orders": {
  "allOf": [
    {
      "$ref": "#/definitions/Pager"
    },
    {
      "type": "object",
      "properties": {
        "ProductName": {
          "type": "string"
        },
        "Quantity": {
          "type": "integer"
        }
      }
    }
  ]
}