mirror of
https://github.com/matrix-org/matrix-spec
synced 2025-12-20 16:38:37 +01:00
9e959f3922
Fixes #784 Add a collapsible list of endpoints to the top of the page for each distinct spec. We do this by storing endpoint metadata on $page and creating a new partial, endpoints-toc.html, which renders it.
121 lines
4.3 KiB
HTML
121 lines
4.3 KiB
HTML
{{/*
|
|
|
|
Render a single HTTP API operation: that is, a method+endpoint combination, given:
|
|
|
|
* `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.
|
|
* `page`: the (Hugo) Page object to store endpoint metadata in the Scratch of. Used to build the endpoints TOC.
|
|
* `module`: the current CS API module name, if any. Used to group endpoints in the TOC.
|
|
|
|
This template renders the operation as a `<section>` containing:
|
|
|
|
* an `<h1>` heading containing the method and endpoint
|
|
* a `<details>` element containing the details, including:
|
|
* operation description
|
|
* basic info about the operation
|
|
* request details
|
|
* response details
|
|
|
|
*/}}
|
|
|
|
{{ $method := .method }}
|
|
{{ $endpoint := .endpoint }}
|
|
{{ $operation_data := .operation_data }}
|
|
{{ $page := .page }}
|
|
{{ $module := .module }}
|
|
|
|
{{ $anchor := "" }}
|
|
{{ if .anchor_base }}
|
|
{{ $anchor = printf "%s_" .anchor_base }}
|
|
{{ end }}
|
|
{{ $anchor = printf "%s%s%s" $anchor (lower $method) (anchorize $endpoint) }}
|
|
|
|
{{/* Collect endpoints for the on-page endpoints TOC */}}
|
|
{{ if $page }}
|
|
{{/* Store each endpoint's metadata in a scratch variable */}}
|
|
{{ $entry := dict "anchor" $anchor "method" $method "endpoint" $endpoint "summary" $operation_data.summary "deprecated" $operation_data.deprecated "module" $module }}
|
|
{{ if not ($page.Scratch.Get "api_endpoints_seen") }}
|
|
{{ $page.Scratch.Set "api_endpoints_seen" dict }}
|
|
{{ end }}
|
|
{{/* Keep a map of seen endpoints. This is necessary as this partial may be
|
|
rendered multiple times for the same endpoint (e.g. in the TOC and
|
|
in the main content), leading to duplicates. */}}
|
|
{{ $seen := $page.Scratch.Get "api_endpoints_seen" }}
|
|
{{ $key := printf "%s|%s" $method $endpoint }}
|
|
{{ if not (index $seen $key) }}
|
|
{{ if not (reflect.IsSlice ($page.Scratch.Get "api_endpoints")) }}
|
|
{{ $page.Scratch.Set "api_endpoints" (slice) }}
|
|
{{ end }}
|
|
{{ $page.Scratch.Add "api_endpoints" (slice $entry) }}
|
|
{{ $page.Scratch.SetInMap "api_endpoints_seen" $key true }}
|
|
{{ end }}
|
|
{{ end }}
|
|
|
|
<section class="rendered-data">
|
|
|
|
<details {{ if not site.Params.ui.rendered_data_collapsed }}open{{ end }}>
|
|
<summary>
|
|
|
|
<h1 id="{{ $anchor }}">
|
|
<span class="http-api-method">{{ $method }}</span>
|
|
<span class="endpoint{{ if $operation_data.deprecated }} deprecated-inline{{ end }}">{{ $endpoint }}</span>
|
|
{{ partial "td/heading-self-link.html" (dict "Anchor" $anchor) }}
|
|
</h1>
|
|
</summary>
|
|
|
|
<hr>
|
|
|
|
{{ if $operation_data.deprecated }}
|
|
{{ partial "alert" (dict "type" "warning" "omit_title" "true" "content" "This API is deprecated and will be removed from a future release.") }}
|
|
{{ end }}
|
|
|
|
{{ if (index $operation_data "x-addedInMatrixVersion") }}
|
|
{{ partial "added-in" (dict "v" (index $operation_data "x-addedInMatrixVersion")) }}
|
|
{{ end }}
|
|
{{ if (index $operation_data "x-changedInMatrixVersion") }}
|
|
{{ partial "changed-in" (dict "changes_dict" (index $operation_data "x-changedInMatrixVersion")) }}
|
|
{{ end -}}
|
|
|
|
{{ $operation_data.description | page.RenderString (dict "display" "block") }}
|
|
|
|
|
|
<table class="basic-info">
|
|
<tr>
|
|
<th>Rate-limited:</th>
|
|
{{ $rate_limited := index $operation_data.responses "429" }}
|
|
<td>{{ if $rate_limited }}Yes{{ else }}No{{ end }}</td>
|
|
</tr>
|
|
<tr>
|
|
<th>Requires authentication:</th>
|
|
{{/*
|
|
Authentication is defined with the `security` key. We assume that the
|
|
key is not set if no authentication is necessary. If the key is set,
|
|
authentication is required unless it contains an item that is an empty
|
|
object.
|
|
*/}}
|
|
{{ $requires_authentication := "Yes" }}
|
|
{{ if $operation_data.security }}
|
|
{{ range $operation_data.security }}
|
|
{{ if eq (len (index $operation_data.security 0)) 0 }}
|
|
{{ $requires_authentication = "Optional" }}
|
|
{{ end }}
|
|
{{ end }}
|
|
{{ else }}
|
|
{{ $requires_authentication = "No" }}
|
|
{{ end }}
|
|
<td>{{ $requires_authentication }}</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<hr>
|
|
{{ partial "openapi/render-request" (dict "parameters" $operation_data.parameters "request_body" $operation_data.requestBody "anchor_base" $anchor ) }}
|
|
<hr>
|
|
{{ partial "openapi/render-responses" (dict "responses" $operation_data.responses "anchor_base" $anchor ) }}
|
|
|
|
</details>
|
|
|
|
</section>
|