Swagger schema properties ignored when using $ref - why?

Question

I'm trying to build a Swagger model for a time interval, using a simple string to store the time (I know that there is also datetime):

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"        

For some reason the generated HTML does not show the lowerBound and upperBound "description", but only the original Time "description". This makes me think I'm not doing this correctly.

So the question is if using a model as a type can in fact be done as I'm trying to do.

Answer 1

$ref works by replacing itself and all of its sibling elements with the definition it is pointing at. That is why

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

becomes

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

A possible workaround is to wrap $ref into allOf - this can be used to "add" attributes to a $ref but not override existing attributes.

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

Another way is to use replace the $ref with an inline definition.

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"

The usability of $ref is being discussed in the OpenAPI spec repository here and here so maybe this will be improved in one of the future versions.