diff --git a/changelogs/internal/newsfragments/1801.clarification b/changelogs/internal/newsfragments/1801.clarification new file mode 100644 index 00000000..6d01cfb7 --- /dev/null +++ b/changelogs/internal/newsfragments/1801.clarification @@ -0,0 +1 @@ +Do not use the `title` of objects containing only `additionalProperties` or `patternProperties`. diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 227e9e04..21d77c89 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -84,6 +84,9 @@ * `oneOf`: optional array of dictionaries describing the different formats that the property can have + * `properties`: if the type is an object, optional dictionary for + well-defined properties, each given as: `property_name` : `property_data` + * `additionalProperties`: if the type is an object, optional dictionary for properties with undefined names @@ -148,6 +151,9 @@ * `title`: optional string for the title of the object property + * `properties`: optional dictionary for well-defined properties, each given + as: `property_name` : `property_data` + * `additionalProperties`: optional dictionary for properties with undefined names @@ -155,19 +161,19 @@ adhering to a regex pattern * `anchor`: optional HTML element id for the target type, which will be used to link to it. - - The title has a higher priority than anything else. */}} {{ define "partials/object-type-or-title" }} {{ $type := "object" }} - {{ if .title }} + {{ if .properties }} {{/* - If the property has a `title`, use that rather than `type`. - This means we can write things like `EventFilter` rather than `object`. + The object has its own (regular) properties, so we will make a + separate table for it. Refer to it using its title, if it has one. */}} - {{ $type = .title | htmlEscape }} - {{ if .anchor }} - {{ $type = printf "%s" (htmlEscape .anchor) $type }} + {{ if .title }} + {{ $type = .title | htmlEscape }} + {{ if .anchor }} + {{ $type = printf "%s" (htmlEscape .anchor) $type }} + {{ end }} {{ end }} {{ else if reflect.IsMap .additionalProperties }} {{/* @@ -218,6 +224,13 @@ {{/* Then join all the formats. */}} {{ $type = delimit $types "|" }} + {{ else if .title }} + {{/* + No properties, so there won't be a separate table. We use the title + anyway, because showing the title (like `EventFilter`) is better + than showing `object`. + */}} + {{ $type = .title | htmlEscape }} {{ end }} {{ return $type }}