Ensure more uniqueness for generated HTML IDs (#1881)

* Include method in all API endpoint children's IDs

Avoids duplicate IDs for object of endpoints
that use the same path but a different method.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Differentiate API endpoints' request and response children's IDs

Ensures that the objects have a unique ID compared to other parts of the endpoint.
Mostly useful for the Error type that can be used for responses with different status codes.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Differentiate the names of both SessionData formats

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

* Add changelog

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

---------

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/internal/newsfragments/1881.clarification

@@ -0,0 +1 @@
+Ensure most generated HTML IDs are unique.

content/client-server-api/modules/end_to_end_encryption.md

@@ -1349,7 +1349,7 @@ the following format:
 The `session_data` field in the backups is constructed as follows:
 
 1.  Encode the session key to be backed up as a JSON object using the
-    `SessionData` format defined below.
+    `BackedUpSessionData` format defined below.
 
 2.  Generate an ephemeral curve25519 key, and perform an ECDH with the
     ephemeral key and the backup's public key to generate a shared
@@ -1427,7 +1427,7 @@ user-supplied passphrase, and is created as follows:
 
 ###### Key export format
 
-The exported sessions are formatted as a JSON array of `SessionData`
+The exported sessions are formatted as a JSON array of `ExportedSessionData`
 objects described as follows:
 
 {{% definition path="api/client-server/definitions/megolm_export_session_data" %}}

data/api/client-server/definitions/key_backup_session_data.yaml

@@ -14,7 +14,7 @@
 
 
 type: object
-title: SessionData
+title: BackedUpSessionData
 description: |-
   The format of a backed-up session key, prior to encryption, when using the
   `m.megolm_backup.v1.curve25519-aes-sha2` algorithm.

data/api/client-server/definitions/megolm_export_session_data.yaml

@@ -16,6 +16,7 @@
 allOf:
   - $ref: key_backup_session_data.yaml
   - type: object
+    title: ExportedSessionData
     description: |-
       The format used to encode a Megolm session key for export.
 

layouts/partials/openapi/render-operation.html

@@ -20,14 +20,14 @@
 {{ $method := .method }}
 {{ $endpoint := .endpoint }}
 {{ $operation_data := .operation_data }}
-{{ $anchor := anchorize $endpoint }}
+{{ $anchor := printf "%s%s" (lower $method) (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 }}{{ $anchor }}">
+  <h1 id="{{ $anchor }}">
    <span class="http-api-method {{ $method }}">{{ $method }}</span>
    <span class="endpoint{{ if $operation_data.deprecated }} deprecated-inline{{ end }}">{{ $endpoint }}</span>
   </h1>

layouts/partials/openapi/render-request.html

@@ -16,6 +16,7 @@
 {{ $parameters := .parameters }}
 {{ $request_body := .request_body }}
 {{ $anchor_base := .anchor_base }}
+{{ $anchor := printf "%s_request" $anchor_base }}
 
 <h2>Request</h2>
 
@@ -42,7 +43,7 @@
             */}}
             {{ $schema := $json_body.schema }}
 
-            {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }}
+            {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }}
             {{ range $additional_types }}
                 {{ partial "openapi/render-object-table" . }}
             {{ end }}

layouts/partials/openapi/render-responses.html

@@ -39,6 +39,7 @@
 
 {{ range $code, $response := $responses }}
     {{ if $response.content }}
+        {{ $anchor := printf "%s_response-%s" $anchor_base $code }}
 <h3>{{$code}} response</h3>
         {{/* Display defined headers */}}
         {{ if $response.headers }}
@@ -97,7 +98,7 @@
             response. (This will be a no-op for response types which aren't
             objects or arrays.)
             */}}
-            {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }}
+            {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }}
             {{ range $additional_types }}
                 {{ partial "openapi/render-object-table" . }}
             {{ end }}