From 1fc25d8d48514b1fc2df0c3e4b015a3746802c22 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 30 Apr 2024 19:05:03 +0200
Subject: [PATCH] Do not use `title` for objects containing only
 `additionalProperties` or `patternProperties` (#1801)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Previously, titles would appear that do not link to a subchema definition.
It would also mean that named subschemas would appear without being clearly referenced.

Now, the type clearly shows the nesting of objects
and subschema definitions should be clearly referenced.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
---
 .../internal/newsfragments/1801.clarification |  1 +
 .../partials/openapi/render-object-table.html | 29 ++++++++++++++-----
 2 files changed, 22 insertions(+), 8 deletions(-)
 create mode 100644 changelogs/internal/newsfragments/1801.clarification

diff --git a/changelogs/internal/newsfragments/1801.clarification b/changelogs/internal/newsfragments/1801.clarification
new file mode 100644
index 000000000..6d01cfb7a
--- /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 227e9e04c..21d77c89e 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 "<a href=\"#%s\">%s</a>" (htmlEscape .anchor) $type }}
+        {{ if .title }}
+          {{ $type = .title | htmlEscape }}
+          {{ if .anchor }}
+              {{ $type = printf "<a href=\"#%s\">%s</a>" (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 }}