Свойства схемы Swagger игнорируются при использовании $ ref - why?

Question

Я пытаюсь построить модель Swagger для временного интервала, используя простую строку для хранения времени (я знаю, что есть также даты и время):

definitions: 
    Time: 
    type: string 
    description: Time in 24 hour format "hh:mm". 
    TimeInterval: 
    type: object 
    properties: 
     lowerBound: 
     $ref: "#/definitions/Time" 
     description: Lower bound on the time interval. 
     default: "00:00" 
     upperBound: 
     $ref: "#/definitions/Time" 
     description: Upper bound on the time interval. 
     default: "24:00"   

По какой-то причине сгенерированного HTML не показывает нижнее нижнее и верхнее «описание», но только оригинальное «описание» времени. Это заставляет меня думать, что я делаю это неправильно.

Итак, вопрос в том, можно ли на самом деле использовать модель как тип, как я пытаюсь сделать.

Answer 1

$ref работает, заменяя себя и все его родственные элементы с указанием, на которое он указывает. Вот почему

 lowerBound: 
     $ref: "#/definitions/Time" 
     description: Lower bound on the time interval. 
     default: "00:00" 

становится

 lowerBound: 
     type: string 
     description: Time in 24 hour format "hh:mm". 

Решение определить атрибуты инлайн:

definitions: 
    TimeInterval: 
    type: object 
    properties: 
     lowerBound: 
     type: string # <------ 
     description: Lower bound on the time interval, using 24 hour format "hh:mm". 
     default: "00:00" 
     upperBound: 
     type: string # <------ 
     description: Upper bound on the time interval, using 24 hour format "hh:mm". 
     default: "24:00" 

Юзабилити $ref обсуждается в OpenAPI хранилище спецификации here и here, так что, возможно, это будет улучшено в следующей версии v3.0.