Present OpenAPI additionalProperties field

When looking at the "Authentication Data" type used in e.g. the account
deactivation endpoint

    https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3accountdeactivate

it was not clear to me that clients and servers should expect additional
fields in this structure (the semantics of which are implied by the
`type` of the authentication, or that of the previously established
`session`.)

In the OpenAPI spec, We occasionally mark some ojects as allowing
arbitrary additional properties (`additionalProperties: true`, or
`additionalProperties: { description: "..."}`). In other places we are
more strict and provide a schema that additional properties must satisfy.
In this PR we aim to make the first kind of additional
properties (non-strict) more visible in the rendered spec.

assets/scss/custom.scss

@@ -370,6 +370,10 @@ footer {
       width: 75%;
     }
 
+    .row-additional-properties {
+      font-style: italic;
+    }
+
   }
 
   pre {

layouts/partials/json-schema/resolve-additional-types.html

@@ -88,5 +88,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 "additionalProperties" .additionalProperties) }}
 {{ end }}

layouts/partials/openapi/render-object-table.html

@@ -14,6 +14,7 @@
 {{ $caption := .caption }}
 {{ $properties := .properties}}
 {{ $required := .required}}
+{{ $additionalProperties := .additionalProperties }}
 
 {{ if $properties }}
 
@@ -93,6 +94,29 @@
 
     {{ end }}
 
+   {{/* NB: the OpenAPI spec says "Consistent with JSON Schema, additionalProperties
+         defaults to true." Our schemas tend to omit additionalProperties; I think we
+         effectively assume it defaults to false. Therefore: we only output regarding
+         additionalProperties if it is explicitly set (i.e. is non-nil). */}}
+   {{ if (ne $additionalProperties nil )}}
+  <tr class="row-additional-properties">
+   <td colspan="3">
+        {{ if (and (reflect.IsMap $additionalProperties)) -}}
+            {{ if (index $additionalProperties "description") -}}
+May have additional properties: {{ $additionalProperties.description }}
+            {{ end }}
+        {{/* TODO: should we handle the case where additional properties are permitted,
+                    but must follow an explicit schema? */}}
+        {{ else if $additionalProperties -}}
+May have additional properties.
+        {{ else if (not $additionalProperties) -}}
+        {{/* At present we don't have any schema with additionalProperties: false.
+        But if we ever do, let's support it. */}}
+May **not** have additional properties.
+        {{ end }}
+   </td>
+  </tr>
+    {{ end }}
 </table>
 
 {{ end }}

layouts/partials/openapi/render-request.html

@@ -41,7 +41,7 @@
         {{ $additional_types := partial "json-schema/resolve-additional-types" $schema }}
         {{ $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" (dict "caption" .title "properties" .properties "required" .required "additionalProperties" .additionalProperties) }}
         {{ end }}
 
 <h3>Request body example</h3>