Combining defintions in Swagger docs

Indeed, the example you give here is invalid because $ref can’t co-exist with other properties in the same object. $ref is a JSON Reference, and by definition, will cause the other properties to be ignored.

From your question, I assume you’re looking for basic composition (rather than inheritance). This is achievable using the allOf keyword.

So, with the example you provided, you would have something like this:

{
  "baseProperties": {
    "type": "object",
    "properties": {
        ...
    }
  },
  "complexModel": {
    "allOf": [
      {
        "$ref": "#/definitions/baseProperties"
      },
      {
        "type": "object",
        "properties": {
          "unique_thing": {
            "type": "string"
          },
          "another_unique_thing": {
            "type": "string"
          }
        }
      }
    ]
  }
}

YAML version:

definitions:
  baseProperties:
    type: object
    properties:
       ...
  complexModel:
    allOf:
      - $ref: '#/definitions/baseProperties'
      - type: object
        properties:
          unique_thing:
            type: string
          another_unique_thing:
            type: string

You can also check out the example in the spec.