Объединение определений в документации Swagger

Я документирую API с помощью документации Swagger. У меня есть несколько конечных точек с общим набором базовых свойств. Я хотел бы использовать $ ref для ссылки на этот базовый набор свойств, а затем расширить эти свойства дополнительными свойствами, уникальными для каждой конечной точки. Я предполагал, что это будет работать примерно так, но это неверно:

"properties": {
    "$ref": "#/definitions/baseProperties",
    unique_thing": {
      "type": "string"
    },
    "another_unique_thing": {
      "type": "string"
    }
 }

swagger swagger-ui
person Bailey Smith    schedule 05.04.2015    source источник

Ответы (1)


arrow_upward
22
arrow_downward

В самом деле, приведенный здесь пример неверен, потому что $ref не может сосуществовать с другими свойствами в одном объекте. $ref является ссылкой JSON и по определению будет вызывать игнорирование других свойств.

Исходя из вашего вопроса, я предполагаю, что вы ищете базовую композицию (а не наследование). Это достигается с помощью ключевого слова allOf.

Итак, в приведенном вами примере у вас будет что-то вроде этого:

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

Версия YAML:

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

Вы также можете посмотреть пример в спецификации.

person Ron    schedule 06.04.2015