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>
This commit is contained in:
parent
bd20d946c4
commit
18628dc5d7
6 changed files with 25 additions and 8 deletions
1
changelogs/internal/newsfragments/1882.clarification
Normal file
1
changelogs/internal/newsfragments/1882.clarification
Normal file
|
@ -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…
Add table
Add a link
Reference in a new issue