@ -6,10 +6,16 @@
* `anchor`: optional HTML element id for the table
* `anchor`: optional HTML element id for the table
* `properties`: dictionary of the properties to list, each given as:
* `properties`: optional dictionary of the properties to list, each given as:
`property_name` : `property_data`
`property_name` : `property_data`
* `required`: array containing the names of required properties.
* `additionalProperties`: optional dictionary for properties with undefined
names, in the same format as `property_data`
* `patternProperties`: optional dictionary for properties with names adhering
to a regex pattern, in the same format as `property_data`
* `required`: optional array containing the names of required properties.
In some cases (such as response body specifications) this isn't used, and
In some cases (such as response body specifications) this isn't used, and
instead properties have a `required` boolean attribute. We support this too.
instead properties have a `required` boolean attribute. We support this too.
@ -34,24 +40,6 @@
{{ range $property_name, $property := $properties }}
{{ range $property_name, $property := $properties }}
{{ $property := partial "json-schema/resolve-allof" $property }}
{{ $property := partial "json-schema/resolve-allof" $property }}
{{ $type := $property.type }}
{{ if or (eq $property.type "object") (and $property.oneOf (reflect.IsSlice .oneOf)) }}
{{ $type = partial "type-or-title" $property }}
{{ end }}
{{/*
If the property is an array, indicate this with square brackets,
like `[type]`.
*/}}
{{ if eq $property.type "array"}}
{{ $items := $property.items }}
{{ if $property.items }}
{{ $items = partial "json-schema/resolve-allof" $property.items }}
{{ end }}
{{ $inner_type := partial "type-or-title" $items }}
{{ $type = delimit (slice "[" $inner_type "]") "" }}
{{ end }}
{{/*
{{/*
Handle two ways of indicating "required", one for simple parameters,
Handle two ways of indicating "required", one for simple parameters,
@ -61,25 +49,93 @@
< tr >
< tr >
< td > < code > {{ $property_name }}< / code > < / td >
< td > < code > {{ $property_name }}< / code > < / td >
< td > < code > {{ $type }}< / code > < / td >
< td > < code > {{ partial "partials/property-type" $property }}< / code > < / td >
< td >
< td > {{ partial "partials/property-description" (dict "property" $property "required" $required) }}< / td >
{{ if $required }}< strong > Required: < / strong > {{end -}}
{{ $property.description | markdownify -}}
{{ if $property.enum }}< p > One of: < code > [{{ delimit $property.enum ", " }}]< / code > .< / p > {{ end -}}
{{ if (index $property "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index $property "x-addedInMatrixVersion")) }}{{ end -}}
{{ if (index $property "x-changedInMatrixVersion") }}{{ partial "changed-in" (dict "changes_dict" (index $property "x-changedInMatrixVersion")) }}{{ end -}}
< / td >
< / tr >
< / tr >
{{ end }}
{{ end }}
< / table > < / table >
{{ else if (or .additionalProperties .patternProperties) }}
< table { { if . anchor } } id = "{{ .anchor }}" { { end } } class = "object-table" >
{{ with $title }}
< caption > {{ . }}< / caption >
{{ end }}
< thead >
< th class = "col-type" > Type< / th >
< th class = "col-description" > Description< / th >
< / thead >
{{ $property := partial "json-schema/resolve-allof" . }}
< tr >
< td > < code > {{ partial "partials/property-type" $property }}< / code > < / td >
< td > {{ partial "partials/property-description" (dict "property" $property) }}< / td >
< / tr >
< / table >
{{ end }}
{{/*
Computes the type to display for a property, given:
* `type`: string or array of strings for the type(s) of the property
* `title`: optional string for the title of the property
* `oneOf`: optional array of dictionaries describing the different formats
that the property can have
* `additionalProperties`: optional dictionary for properties with undefined
names
* `patternProperties`: optional dictionary for properties with names
adhering to a regex pattern
* `items`: if the type is an array, array of dictionaries describing the
format of the array's items
*/}}
{{ define "partials/property-type" }}
{{ $type := .type }}
{{ if or (eq .type "object") (and .oneOf (reflect.IsSlice .oneOf)) }}
{{ $type = partial "type-or-title" . }}
{{ end }}
{{/*
If the property is an array, indicate this with square brackets,
like `[type]`.
*/}}
{{ if eq .type "array"}}
{{ $items := .items }}
{{ if .items }}
{{ $items = partial "json-schema/resolve-allof" .items }}
{{ end }}
{{ $inner_type := partial "type-or-title" $items }}
{{ $type = delimit (slice "[" $inner_type "]") "" }}
{{ end }}
{{ return $type }}
{{ end }}
{{ end }}
{{/*
{{/*
Picks either the `title` of a property, or the `type`, to turn into the rendered type field.
Computes the type to display for a property's schema, given:
Also handles `additionalProperties`, if no `title` is present.
* `type`: string or array of strings for the type(s) of the property
* `title`: optional string for the title of the property
* `oneOf`: optional array of dictionaries describing the different formats
that the property can have
* `additionalProperties`: optional dictionary for properties with undefined
names
* `patternProperties`: optional dictionary for properties with names
adhering to a regex pattern
The title has a higher priority than anything else.
*/}}
*/}}
{{ define "partials/type-or-title" }}
{{ define "partials/type-or-title" }}
{{ $type := "" }}
{{ $type := "" }}
@ -94,7 +150,24 @@
If the property uses `additionalProperties` to describe its
If the property uses `additionalProperties` to describe its
internal structure, handle this with a bit of recursion
internal structure, handle this with a bit of recursion
*/}}
*/}}
{{ $type = delimit (slice "{string: " (partial "type-or-title" .additionalProperties) "}" ) "" }}
{{ $additionalProperties := partial "json-schema/resolve-allof" .additionalProperties }}
{{ $type = delimit (slice "{string: " (partial "property-type" $additionalProperties) "}" ) "" }}
{{ else if reflect.IsMap .patternProperties }}
{{/*
If the property uses `patternProperties` to describe its
internal structure, handle this with a bit of recursion.
Note that we ignore the pattern as the current definitions
always have a single pattern, but we might need to handle
them later to differentiate schemas according to patterns.
*/}}
{{ $types := slice }}
{{ range $pattern, $schema := .patternProperties}}
{{ $schema = partial "json-schema/resolve-allof" $schema }}
{{ $types = $types | append (partial "property-type" $schema) }}
{{ end }}
{{ $type = delimit (slice "{string: " (delimit $types "|") "}" ) "" }}
{{ else if reflect.IsSlice .type }}
{{ else if reflect.IsSlice .type }}
{{/* It's legal to specify an array of types. Join them together in that case */}}
{{/* It's legal to specify an array of types. Join them together in that case */}}
@ -123,3 +196,28 @@
{{ end }}
{{ end }}
{{ return $type }}
{{ return $type }}
{{ end }}
{{ end }}
{{/*
Computes the description to display for a property, given:
* `required`: boolean indicating whether this property is required.
* `property`: dictionary describing the property's data, with these fields:
* `description`: string describing the property
* `enum`: optional array indicating the accepted values for the property
* `x-addedInMatrixVersion`: optional string indicating in which Matrix
spec version this property was added.
* `x-changedInMatrixVersion`: optional string indicating in which Matrix
spec version this property was last changed.
*/}}
{{ define "partials/property-description" }}
{{ if .required }}< strong > Required: < / strong > {{end -}}
{{ .property.description | markdownify -}}
{{ if .property.enum }}< p > One of: < code > [{{ delimit .property.enum ", " }}]< / code > .< / p > {{ end -}}
{{ if (index .property "x-addedInMatrixVersion") }}{{ partial "added-in" (dict "v" (index .property "x-addedInMatrixVersion")) }}{{ end -}}
{{ if (index .property "x-changedInMatrixVersion") }}{{ partial "changed-in" (dict "changes_dict" (index .property "x-changedInMatrixVersion")) }}{{ end -}}
{{ end }}
Kévin Commaille
1 year ago
committed by