From 07645fc1ad91be92e7bf8f576d89a7438c291341 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 24 Apr 2024 12:27:53 +0200 Subject: [PATCH 1/6] Do not use title for objects containing only additionalProperties or patternProperties 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 --- layouts/partials/openapi/render-object-table.html | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 6faa21d9f..175ba038b 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -155,12 +155,10 @@ 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 and .title (or .properties (not (or .additionalProperties .patternProperties))) }} {{/* If the property has a `title`, use that rather than `type`. This means we can write things like `EventFilter` rather than `object`. From 450c1472785953f16da43d7d974e1b1629ab41dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 24 Apr 2024 12:45:09 +0200 Subject: [PATCH 2/6] Add changelog MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- changelogs/internal/newsfragments/1801.clarification | 1 + 1 file changed, 1 insertion(+) 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`. From 52da0752637f8244fa1a56423096963a3258e229 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Wed, 24 Apr 2024 14:40:11 +0200 Subject: [PATCH 3/6] Improve docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- layouts/partials/openapi/render-object-table.html | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 175ba038b..17bed313d 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -160,8 +160,12 @@ {{ $type := "object" }} {{ if and .title (or .properties (not (or .additionalProperties .patternProperties))) }} {{/* - If the property has a `title`, use that rather than `type`. - This means we can write things like `EventFilter` rather than `object`. + We only want to use the title in two cases: + + * The object is rendered as a separate table that will use the same + title, which means that the object must have `properties`. + * The object doesn't define any properties, because showing the title + (like `EventFilter`) is better than showing `object`. */}} {{ $type = .title | htmlEscape }} {{ if .anchor }} From 7c5e123f4fa30da2eee1563aa6a23beecfd82611 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 30 Apr 2024 18:08:27 +0200 Subject: [PATCH 4/6] Refactor if-else blocks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../partials/openapi/render-object-table.html | 25 +++++++++++-------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 17bed313d..179f6ab9f 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -158,18 +158,16 @@ */}} {{ define "partials/object-type-or-title" }} {{ $type := "object" }} - {{ if and .title (or .properties (not (or .additionalProperties .patternProperties))) }} + {{ if .properties }} {{/* - We only want to use the title in two cases: - - * The object is rendered as a separate table that will use the same - title, which means that the object must have `properties`. - * The object doesn't define any properties, because showing the title - (like `EventFilter`) is better than showing `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 }} {{/* @@ -192,6 +190,13 @@ {{ end }} {{ $type = delimit (slice "{string: " (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 }} {{ end }} {{ return $type }} From d33635bdf974e330ade1f7e6667e3c22bc5e1d52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 30 Apr 2024 18:16:30 +0200 Subject: [PATCH 5/6] Escape title MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- layouts/partials/openapi/render-object-table.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index 179f6ab9f..598b12a38 100644 --- a/layouts/partials/openapi/render-object-table.html +++ b/layouts/partials/openapi/render-object-table.html @@ -196,7 +196,7 @@ anyway, because showing the title (like `EventFilter`) is better than showing `object`. */}} - {{ $type = .title }} + {{ $type = .title | htmlEscape }} {{ end }} {{ return $type }} From 4a1a881f48e595f145dc3b48d66b6dca3f406629 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 30 Apr 2024 18:57:41 +0200 Subject: [PATCH 6/6] Document properties input for partials MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- layouts/partials/openapi/render-object-table.html | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html index e1773c58c..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