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.
This notation lets you specify the target file or a specific part of a file you want to reference. In the previous example, #/components/schemas/User means the resolving starts from the root of the current document, and then finds the values of components , schemas , and User one after another.
OpenAPI 3.0 data types are based on an extended subset JSON Schema Specification Wright Draft 00 (aka Draft 5). The data types are described using a Schema object. To learn how to model various data types, see the following topics: Data Types.
The additionalProperties keyword specifies the type of values in the dictionary. Values can be primitives (strings, numbers or boolean values), arrays or objects. For example, a string-to-object dictionary can be defined as follows: type: object.
TL;DR: $ref
siblings are supported in OpenAPI 3.1. In previous OpenAPI versions, any keywords alongside $ref
are ignored.
Your definition will work as expected when migrated to OpenAPI 3.1. This new version is fully compatible with JSON Schema 2020-12, which allows $ref
siblings in schemas.
openapi: 3.1.0 ... components: schemas: Time: type: string description: Time in 24 hour format "hh:mm". TimeInterval: type: object properties: lowerBound: # ------- This will work in OAS 3.1 ------- # $ref: "#/components/schemas/Time" description: Lower bound on the time interval. default: "00:00" upperBound: # ------- This will work in OAS 3.1 ------- # $ref: "#/components/schemas/Time" description: Upper bound on the time interval. default: "24:00"
Outside of schemas - for example, in responses or parameters - $refs only allow sibling summary
and description
keywords. Any other keywords alongside these $refs will be ignored.
# openapi: 3.1.0 # This is supported parameters: - $ref: '#/components/parameters/id' description: Entity ID # This is NOT supported parameters: - $ref: '#/components/parameters/id' required: true
In these versions, $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"
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With