From 5f3b34448d1b4582c9533ccc28a8986dc722094d Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Tue, 19 Jul 2022 20:25:30 +0100
Subject: [PATCH] Add HTML ids for object definitions in the formatted
 specification (#1174)

* Remove redundant call to resolve-allof

All of the callers to resolve-additional-types already call resolve-allof (or
if not, they should), so this is redundant.

* Update `resolve-additional-types` to take a dict

I want to add more params to this, so first make it take a dict.

* `render-object-table`: take a "title" rather than a "caption"

... which means we can use the result from resolve-additional-types directly.

* render-object-table: support adding an anchor to generated tables.

* resolve-additional-types: generate an id for each returned type

* render-event: pass an anchor_base into resolve-additional-types

This means that it will generate an anchor for each type, whihc will then be
passed into render-object-table and used as an `id` for the table.

* render-operation: pass an anchor_base into resolve-additional-types

* newsfiles
---
 .../newsfragments/1174.clarification          |  1 +
 .../newsfragments/1174.clarification          |  1 +
 .../newsfragments/1174.clarification          |  1 +
 .../newsfragments/1174.clarification          |  1 +
 .../newsfragments/1174.clarification          |  1 +
 layouts/partials/events/render-event.html     |  5 ++-
 .../json-schema/resolve-additional-types.html | 43 ++++++++++++-------
 .../partials/openapi/render-object-table.html | 18 +++++---
 .../partials/openapi/render-operation.html    |  7 +--
 .../partials/openapi/render-parameters.html   |  2 +-
 layouts/partials/openapi/render-request.html  |  6 ++-
 .../partials/openapi/render-responses.html    |  6 ++-
 layouts/shortcodes/definition.html            |  4 +-
 layouts/shortcodes/event-fields.html          |  4 +-
 14 files changed, 64 insertions(+), 36 deletions(-)
 create mode 100644 changelogs/application_service/newsfragments/1174.clarification
 create mode 100644 changelogs/client_server/newsfragments/1174.clarification
 create mode 100644 changelogs/identity_service/newsfragments/1174.clarification
 create mode 100644 changelogs/push_gateway/newsfragments/1174.clarification
 create mode 100644 changelogs/server_server/newsfragments/1174.clarification

diff --git a/changelogs/application_service/newsfragments/1174.clarification b/changelogs/application_service/newsfragments/1174.clarification
new file mode 100644
index 00000000..9eef7945
--- /dev/null
+++ b/changelogs/application_service/newsfragments/1174.clarification
@@ -0,0 +1 @@
+Add HTML anchors for object definitions in the formatted specification.
diff --git a/changelogs/client_server/newsfragments/1174.clarification b/changelogs/client_server/newsfragments/1174.clarification
new file mode 100644
index 00000000..9eef7945
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1174.clarification
@@ -0,0 +1 @@
+Add HTML anchors for object definitions in the formatted specification.
diff --git a/changelogs/identity_service/newsfragments/1174.clarification b/changelogs/identity_service/newsfragments/1174.clarification
new file mode 100644
index 00000000..9eef7945
--- /dev/null
+++ b/changelogs/identity_service/newsfragments/1174.clarification
@@ -0,0 +1 @@
+Add HTML anchors for object definitions in the formatted specification.
diff --git a/changelogs/push_gateway/newsfragments/1174.clarification b/changelogs/push_gateway/newsfragments/1174.clarification
new file mode 100644
index 00000000..9eef7945
--- /dev/null
+++ b/changelogs/push_gateway/newsfragments/1174.clarification
@@ -0,0 +1 @@
+Add HTML anchors for object definitions in the formatted specification.
diff --git a/changelogs/server_server/newsfragments/1174.clarification b/changelogs/server_server/newsfragments/1174.clarification
new file mode 100644
index 00000000..9eef7945
--- /dev/null
+++ b/changelogs/server_server/newsfragments/1174.clarification
@@ -0,0 +1 @@
+Add HTML anchors for object definitions in the formatted specification.
diff --git a/layouts/partials/events/render-event.html b/layouts/partials/events/render-event.html
index 66e15db7..5e9f5c13 100644
--- a/layouts/partials/events/render-event.html
+++ b/layouts/partials/events/render-event.html
@@ -53,10 +53,11 @@
 
 <h2>Content</h2>
 
-{{ $additional_types := partial "json-schema/resolve-additional-types" $event_data.properties.content }}
+{{ $anchor_base := anchorize $event_name }}
+{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $event_data.properties.content "anchor_base" $anchor_base) }}
 
 {{ range $additional_types }}
-    {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }}
+    {{ partial "openapi/render-object-table" . }}
 {{end}}
 
 <h2>Examples</h2>
diff --git a/layouts/partials/json-schema/resolve-additional-types.html b/layouts/partials/json-schema/resolve-additional-types.html
index 26df52e5..63a15bee 100644
--- a/layouts/partials/json-schema/resolve-additional-types.html
+++ b/layouts/partials/json-schema/resolve-additional-types.html
@@ -1,25 +1,34 @@
 {{/*
 
-  Finds and returns all nested objects, given:
+  Finds and returns all nested objects, given a dict containing:
+   * `schema`: a JSON schema object
+   * `anchor_base`: a prefix to add to the HTML anchors generated for each object. If nil, no anchors are generated.
 
-  * `this_object`: a JSON schema object
+  This template finds all nested objects inside `schema`.
 
-  Given a schema object, this template finds all nested objects under that
-  schema.
+  Assumes that "resolve-refs" and "resolve-allof" has already been called on the
+  input schema.
 
-  It "cleans" each object by copying only the parts of the objects that
-  the renderer needs, and adds the result to an array, `additional_objects`.
-
-  Finally it returns the array of all the objects it found.
+  Returns an array of all the objects found. For each object, the following properties are returned:
+    * title
+    * properties
+    * required
+    * enum
+    * anchor: a string suitable for using as an html anchor for this object (if `anchor_base` was set, and the object has a title)
 
   Note that the returned array may contain duplicate objects.
 
 */}}
 
-{{ $this_object := partial "json-schema/resolve-allof" . }}
+{{ $this_object := .schema }}
+{{ $anchor_base := .anchor_base }}
 {{ $additional_objects := slice }}
 
 {{ if eq $this_object.type "object" }}
+    {{/* give this object an anchor, if it has a name */}}
+    {{ if (and $anchor_base $this_object.title) }}
+        {{ $this_object = merge $this_object (dict "anchor" (printf "%s_%s" $anchor_base (anchorize $this_object.title))) }}
+    {{ end }}
 
     {{/*
       Add the object we were passed into the $additional_objects array
@@ -34,7 +43,7 @@
             {{ $additional_objects = $additional_objects | append (partial "clean-object" $this_object.additionalProperties) }}
 
             {{ range $key, $property := $this_object.additionalProperties.properties }}
-                {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $property "additional_objects" $additional_objects) }}
+                {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $property "additional_objects" $additional_objects "anchor_base" $anchor_base) }}
             {{ end }}
 
         {{ end }}
@@ -44,7 +53,7 @@
       Add any nested objects referenced in this object's `properties`
     */}}
     {{ range $key, $property := $this_object.properties}}
-        {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $property "additional_objects" $additional_objects) }}
+        {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $property "additional_objects" $additional_objects "anchor_base" $anchor_base) }}
     {{ end }}
 
 {{ end }}
@@ -55,10 +64,10 @@
     */}}
     {{ if reflect.IsSlice $this_object.items}}
         {{ range $this_object.items }}
-            {{ $additional_objects = partial "get-additional-objects" (dict "this_object" . "additional_objects" $additional_objects) }}
+            {{ $additional_objects = partial "get-additional-objects" (dict "this_object" . "additional_objects" $additional_objects "anchor_base" $anchor_base) }}
         {{ end }}
     {{ else }}
-        {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $this_object.items "additional_objects" $additional_objects) }}
+        {{ $additional_objects = partial "get-additional-objects" (dict "this_object" $this_object.items "additional_objects" $additional_objects "anchor_base" $anchor_base) }}
     {{ end }}
 {{ end }}
 
@@ -71,8 +80,12 @@
 {{ define "partials/get-additional-objects" }}
     {{ $additional_objects := .additional_objects }}
 
+    /* although we expect resolve-allof to be called on the input, resolve-allof does not recurse into
+     * nested objects, so we have to call it again.
+     */
     {{ $this_object := partial "json-schema/resolve-allof" .this_object }}
-    {{ $more_objects := partial "json-schema/resolve-additional-types" $this_object }}
+
+    {{ $more_objects := partial "json-schema/resolve-additional-types" (dict "schema" $this_object "anchor_base" .anchor_base) }}
     {{/*
       As far as I know we don't have something like Array.concat(), so add them one at a time
     */}}
@@ -88,5 +101,5 @@
   but with (for example) different examples will be considered different.
 */}}
 {{ define "partials/clean-object" }}
-    {{ return (dict "title" .title "properties" .properties "required" .required "enum" .enum) }}
+    {{ return (dict "title" .title "properties" .properties "required" .required "enum" .enum "anchor" .anchor) }}
 {{ end }}
diff --git a/layouts/partials/openapi/render-object-table.html b/layouts/partials/openapi/render-object-table.html
index e132af30..7de88071 100644
--- a/layouts/partials/openapi/render-object-table.html
+++ b/layouts/partials/openapi/render-object-table.html
@@ -2,23 +2,27 @@
 
   Render a table listing the properties of an object, given:
 
-  * `caption`: optional caption for the table
+  * `title`: optional caption for the table
+
+  * `anchor`: optional HTML element id for the table
+
   * `properties`: 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.
-  In some cases (such as response body specifications) this isn't used, and
-  instead properties have a `required` boolean attribute. We support this too.
+    In some cases (such as response body specifications) this isn't used, and
+    instead properties have a `required` boolean attribute. We support this too.
 
 */}}
 
-{{ $caption := .caption }}
+{{ $title := .title }}
 {{ $properties := .properties}}
 {{ $required := .required}}
 
 {{ if $properties }}
 
-<table class>
- {{ with $caption }}
+<table{{ if .anchor }} id="{{ .anchor }}"{{ end }}>
+ {{ with $title }}
  <caption>{{ . }}</caption>
  {{ end }}
  <thead>
diff --git a/layouts/partials/openapi/render-operation.html b/layouts/partials/openapi/render-operation.html
index 6d516d06..74b729cf 100644
--- a/layouts/partials/openapi/render-operation.html
+++ b/layouts/partials/openapi/render-operation.html
@@ -22,13 +22,14 @@
 {{ $endpoint := .endpoint }}
 {{ $operation_data := .operation_data }}
 {{ $path := .path }}
+{{ $anchor := anchorize $endpoint }}
 
 <section class="rendered-data http-api {{ $method }}">
 
 <details {{ if not site.Params.ui.rendered_data_collapsed }}open{{ end }}>
 <summary>
 
-  <h1 id="{{ lower $method }}{{ anchorize $endpoint }}">
+  <h1 id="{{ lower $method }}{{ $anchor }}">
    <span class="http-api-method {{ $method }}">{{ $method }}</span>
    <span class="endpoint{{ if $operation_data.deprecated }} deprecated-inline{{ end }}">{{ $endpoint }}</span>
   </h1>
@@ -63,9 +64,9 @@
 </table>
 
 <hr/>
-{{ partial "openapi/render-request"   (dict "parameters" $operation_data.parameters "path" $path) }}
+{{ partial "openapi/render-request"   (dict "parameters" $operation_data.parameters "path" $path "anchor_base" $anchor ) }}
 <hr/>
-{{ partial "openapi/render-responses" (dict "responses"  $operation_data.responses  "path" $path) }}
+{{ partial "openapi/render-responses" (dict "responses"  $operation_data.responses  "path" $path "anchor_base" $anchor ) }}
 
 </details>
 
diff --git a/layouts/partials/openapi/render-parameters.html b/layouts/partials/openapi/render-parameters.html
index 2a36ea8d..b7861b7f 100644
--- a/layouts/partials/openapi/render-parameters.html
+++ b/layouts/partials/openapi/render-parameters.html
@@ -25,6 +25,6 @@
     {{ end }}
 
     {{/* and render the parameters */}}
-    {{ partial "openapi/render-object-table" (dict "caption" $caption "properties" $param_dict) }}
+    {{ partial "openapi/render-object-table" (dict "title" $caption "properties" $param_dict) }}
 
 {{ end }}
diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html
index 5e801299..be39fa38 100644
--- a/layouts/partials/openapi/render-request.html
+++ b/layouts/partials/openapi/render-request.html
@@ -4,6 +4,7 @@
 
   * `parameters`: OpenAPI/Swagger data specifying the parameters
   * `path`: the path where this definition was found, to enable us to resolve "$ref"
+  * `anchor_base`: a prefix to add to the HTML anchors generated for each object
 
   This template renders:
   * the "simple parameters" (header, path, query parameters)
@@ -14,6 +15,7 @@
 
 {{ $parameters := .parameters }}
 {{ $path := .path }}
+{{ $anchor_base := .anchor_base }}
 
 <h2>Request</h2>
 
@@ -38,10 +40,10 @@
         {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body_parameter.schema "path" $path) }}
         {{ $schema := partial "json-schema/resolve-allof" $schema }}
 
-        {{ $additional_types := partial "json-schema/resolve-additional-types" $schema }}
+        {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }}
         {{ $additional_types = uniq $additional_types }}
         {{ range $additional_types }}
-            {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }}
+            {{ partial "openapi/render-object-table" . }}
         {{ end }}
 
 <h3>Request body example</h3>
diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html
index 79636945..c6556fbb 100644
--- a/layouts/partials/openapi/render-responses.html
+++ b/layouts/partials/openapi/render-responses.html
@@ -4,6 +4,7 @@
 
   * `responses`: OpenAPI/Swagger data specifying the responses
   * `path`: the path where this definition was found, to enable us to resolve "$ref"
+  * `anchor_base`: a prefix to add to the HTML anchors generated for each object
 
   This template renders:
   * a summary of all the different responses
@@ -15,6 +16,7 @@
 
 {{ $responses := .responses }}
 {{ $path := .path }}
+{{ $anchor_base := .anchor_base }}
 
 <h2>Responses</h2>
 
@@ -71,10 +73,10 @@
           response. (This will be a no-op for response types which aren't
           objects or arrays.)
         */}}
-        {{ $additional_types := partial "json-schema/resolve-additional-types" $schema }}
+        {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }}
         {{ $additional_types = uniq $additional_types }}
         {{ range $additional_types }}
-            {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }}
+            {{ partial "openapi/render-object-table" . }}
         {{ end }}
 
         {{/*
diff --git a/layouts/shortcodes/definition.html b/layouts/shortcodes/definition.html
index 2e000c73..2828db48 100644
--- a/layouts/shortcodes/definition.html
+++ b/layouts/shortcodes/definition.html
@@ -45,11 +45,11 @@
 
 </summary>
 
-{{ $additional_types := partial "json-schema/resolve-additional-types" $definition }}
+{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $definition) }}
 {{ $additional_types = uniq $additional_types }}
 
 {{ range $additional_types }}
-    {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }}
+    {{ partial "openapi/render-object-table" . }}
 {{end}}
 
 <h2>Examples</h2>
diff --git a/layouts/shortcodes/event-fields.html b/layouts/shortcodes/event-fields.html
index 83651c21..7120f87f 100644
--- a/layouts/shortcodes/event-fields.html
+++ b/layouts/shortcodes/event-fields.html
@@ -35,9 +35,9 @@
 
 {{ $event = merge $event (dict "title" "") }}
 
-{{ $additional_types := partial "json-schema/resolve-additional-types" $event }}
+{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $event) }}
 {{ range $additional_types }}
-    {{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required) }}
+    {{ partial "openapi/render-object-table" . }}
 {{end}}
 
 </details>