Allow to specify a prefix for generated HTML IDs of API endpoints (#1882)

* Allow to specify a prefix for generated HTML IDs of API endpoints

Allows to deduplicate IDs of duplicate endpoints

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/1882.clarification

@@ -0,0 +1 @@
+Allow to specify a prefix for generated HTML IDs of API endpoints.

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

@@ -21,7 +21,7 @@ Clients can of course also call other endpoints such as [GET
 and [GET /search](#post_matrixclientv3search) to
 access events outside the `/events` stream.
 
-{{% http-api spec="client-server" api="peeking_events" %}}
+{{% http-api spec="client-server" api="peeking_events" anchor_base="peeking" %}}
 
 #### Server behaviour
 

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

@@ -33,7 +33,7 @@ invitee does indeed own that third-party identifier. See the
 
 A client asks a server to invite a user by their third-party identifier.
 
-{{% http-api spec="client-server" api="third_party_membership" %}}
+{{% http-api spec="client-server" api="third_party_membership" anchor_base="thirdparty" %}}
 
 #### Server behaviour
 

layouts/partials/openapi/render-api.html

@@ -5,11 +5,16 @@
   * `api_data`: the OpenAPI data
   * `base_url`: the base URL: that is, the part we glue onto the front
   of each value in `paths` to get a complete URL.
+  * `anchor_base`: an optional prefix for the HTML IDs generated by
+  this template.
+
+  This template replaces the old {{*_http_api}} template.
 
 */}}
 
 {{ $api_data := index .api_data }}
 {{ $base_url := .base_url }}
+{{ $anchor_base := .anchor_base }}
 
 {{ range $path_name, $path_data := $api_data.paths }}
 
@@ -21,28 +26,28 @@
 
     {{ with $path_data.get }}
 
-        {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . ) }}
+        {{ $operation_params := merge $params (dict "method" "GET" "operation_data" . "anchor_base" $anchor_base) }}
         {{ partial "openapi/render-operation" $operation_params }}
 
     {{ end }}
 
     {{ with $path_data.post }}
 
-        {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . ) }}
+        {{ $operation_params := merge $params (dict "method" "POST" "operation_data" . "anchor_base" $anchor_base) }}
         {{ partial "openapi/render-operation" $operation_params }}
 
     {{ end }}
 
     {{ with $path_data.put }}
 
-        {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . ) }}
+        {{ $operation_params := merge $params (dict "method" "PUT" "operation_data" . "anchor_base" $anchor_base) }}
         {{ partial "openapi/render-operation" $operation_params }}
 
     {{ end }}
 
     {{ with $path_data.delete }}
 
-        {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . ) }}
+        {{ $operation_params := merge $params (dict "method" "DELETE" "operation_data" . "anchor_base" $anchor_base) }}
         {{ partial "openapi/render-operation" $operation_params }}
 
     {{ end }}

layouts/partials/openapi/render-operation.html

@@ -5,6 +5,8 @@
   * `method`: the method, e.g. GET, PUT
   * `endpoint`: the endpoint
   * `operation_data`: the OpenAPI data for the operation
+  * `anchor_base`: an optional prefix for the HTML IDs generated by
+  this template.
 
   This template renders the operation as a `<section>` containing:
 
@@ -20,7 +22,12 @@
 {{ $method := .method }}
 {{ $endpoint := .endpoint }}
 {{ $operation_data := .operation_data }}
-{{ $anchor := printf "%s%s" (lower $method) (anchorize $endpoint) }}
+
+{{ $anchor := "" }}
+{{ if .anchor_base }}
+  {{ $anchor = printf "%s_" .anchor_base }}
+{{ end }}
+{{ $anchor = printf "%s%s%s" $anchor (lower $method) (anchorize $endpoint) }}
 
 <section class="rendered-data http-api {{ $method }}">
 

layouts/shortcodes/http-api.html

@@ -11,6 +11,9 @@
   The file extension is omitted. For example:
 
       {{% http-api spec="server-server" api="public_rooms" %}}
+  * an optional `anchor_base` parameter, which should be used as a
+  prefix for the HTML IDs generated by this template. It should only
+  be necessary to provide one for duplicate endpoints.
 
   This template replaces the old {{*_http_api}} template.
 
@@ -18,6 +21,7 @@
 
 {{ $spec := .Params.spec}}
 {{ $api := .Params.api}}
+{{ $anchor_base := .Params.anchor_base}}
 
 {{ $api_data := index .Site.Data.api .Params.spec .Params.api }}
 {{ $base_url := (index $api_data.servers 0).variables.basePath.default }}
@@ -26,4 +30,4 @@
 {{ $api_data = partial "json-schema/resolve-refs" (dict "schema" $api_data "path" $path) }}
 {{ $api_data = partial "json-schema/resolve-allof" $api_data }}
 
-{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url) }}
+{{ partial "openapi/render-api" (dict "api_data" $api_data "base_url" $base_url "anchor_base" $anchor_base) }}