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>
pull/1885/head
Kévin Commaille 5 months ago committed by GitHub
parent bd20d946c4
commit 18628dc5d7
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

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

@ -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

@ -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

@ -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 }}

@ -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 }}">

@ -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) }}

Loading…
Cancel
Save