Swagger: добавить описание с ref

Я хочу добавить описание к свойству объекта, на которое ссылается его определение. Что-то вроде этого: 

      newCreditCard:
        type: object
        properties:
          billingPhone:
            description: Phone number of the card holder
            $ref: "#/definitions/PhoneNumber"

Но редактор предупреждает, что свойство description будет пропущено:

Extra JSON Reference properties will be ignored: description

Я нашел менее элегантный обходной путь, который работает для редактора, но не для Swagger UI (не уверен, что это возможно из-за недавнего обновления до версии 3.0.2 Swagger UI)

      newCreditCard:
        type: object
        properties:
          billingPhone:
            description: Phone number of the card holder
            allOf:
            - $ref: "#/definitions/PhoneNumber"

Как вы это делаете в своей спецификации Swaggers?

Спасибо за помогите!

2 2
swagger-ui

2 ответа:

Если вы добавите что-либо к тому же уровню $ref, это будет проигнорировано .

JSON $ref definition https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3

Правильный способ заключается в том, чтобы предоставить описание в объекте ссылки.

0

Можно просто переместить свойство description в определение PhoneNumber. Ваш исходный пост не показывает, как вы определили PhoneNumber, но этот фрагмент проверяет без предупреждений: 

definitions:
  phoneNumber:
    type: string
    description: Phone number of the card holder

  newCreditCard:
    type: object
    properties:
      billingPhone:
        $ref: "#/definitions/phoneNumber"
Если этот ответ не является тем, что вы ищете, пожалуйста, повторите вопрос. Нам нужно знать, чего вы добиваетесь.
0