Swagger: Добавить описание с реф.

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

      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 (не уверен, что это может быть связано с недавним обновлением версии 3.0.2 пользовательского интерфейса Swagger)

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

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

Спасибо за помощь!


swagger swagger-ui swagger-editor
person Jonathan Huet    schedule 24.03.2017    source источник
comment
Обходной путь из 2-го примера должен работать в последних версиях Swagger UI.   -  person Helen    schedule 27.09.2019

Ответы (2)


arrow_upward
0
arrow_downward

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

json $ ref определение https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3

правильный способ - предоставить описание в указанном объекте.

person Arun Killu    schedule 06.08.2017
comment
По этому поводу есть проблема. 2 года, все еще не решен. github.com/OAI/OpenAPI-Specification/issues/556 - person Gebb; 21.04.2018
comment
Однако есть несколько телефонных номеров, например один - номер телефона держателя карты, а другой - номер телефона банка и т. д. Поэтому я не понимаю, насколько правильно давать описание в указанном объекте, то есть в определении типа PhoneNumber. - person ChrisW; 23.11.2019

arrow_upward
0
arrow_downward

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

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

  newCreditCard:
    type: object
    properties:
      billingPhone:
        $ref: "#/definitions/phoneNumber"

Если этот ответ не является тем, что вы ищете, пожалуйста, сформулируйте вопрос еще раз. Нам нужно знать, чего вы пытаетесь достичь.

person Dave Delay    schedule 24.03.2017
comment
Предполагая, что целью $ ref является повторное использование определения, тогда единственное определение phoneNumber должно быть доступно для «держателя карты», «мобильного», «домашнего», «факса», «рабочего» номера. .. вы поняли. Все эти описания не могут быть помещены в определение phoneNumber, но должны быть применены к определениям, которые ссылаются на определение phoneNumber. Похоже, что Swagger (или это базовая спецификация JSONReference?) Делает это трудным или, по крайней мере, неочевидным. - person Steve Henty; 11.05.2017
comment
Приложение: эта ветка указывает, что это ограничение спецификации JSONReference - groups.google .com / forum / #! topic / swagger-swaggersocket /. Согласитесь со всеми оценками, что это позор, потому что это действительно делает невозможным повторное использование при определенных обстоятельствах. - person Steve Henty; 11.05.2017
comment
Цель отделения свойства описания от модели phoneNumber состоит в том, чтобы позволить иметь несколько свойств с разным описанием, но с использованием одной и той же модели. Например, billingPhone Номер телефона держателя карты, но, например, для факса, описание должно быть Факс главного офиса. Для обеих моделей все определения одинаковы, за исключением описания. Спасибо за ответ и помощь - person Jonathan Huet; 22.05.2017