mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-03-26 04:54:10 +01:00
c69ac3bb68
When looking at the "Authentication Data" type used in e.g. the account
deactivation endpoint
https://spec.matrix.org/v1.3/client-server-api/#post_matrixclientv3accountdeactivate
it was not clear to me that clients and servers should expect additional
fields in this structure (the semantics of which are implied by the
`type` of the authentication, or that of the previously established
`session`.)
In the OpenAPI spec, We occasionally mark some ojects as allowing
arbitrary additional properties (`additionalProperties: true`, or
`additionalProperties: { description: "..."}`). In other places we are
more strict and provide a schema that additional properties must satisfy.
In this PR we aim to make the first kind of additional
properties (non-strict) more visible in the rendered spec.
62 lines
2.2 KiB
HTML
62 lines
2.2 KiB
HTML
{{/*
|
|
|
|
Render the request part of a single HTTP API operation, given:
|
|
|
|
* `parameters`: OpenAPI/Swagger data specifying the parameters
|
|
* `path`: the path where this definition was found, to enable us to resolve "$ref"
|
|
|
|
This template renders:
|
|
* the "simple parameters" (header, path, query parameters)
|
|
* body parameters, which may be more complex, containing nested objects
|
|
* response body examples
|
|
|
|
*/}}
|
|
|
|
{{ $parameters := .parameters }}
|
|
{{ $path := .path }}
|
|
|
|
<h2>Request</h2>
|
|
|
|
{{ if $parameters }}
|
|
|
|
{{ $simple_parameters := where $parameters "in" "!=" "body"}}
|
|
{{ if $simple_parameters }}
|
|
<h3>Request parameters</h3>
|
|
|
|
{{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "header" "caption" "header parameters") }}
|
|
{{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "path" "caption" "path parameters") }}
|
|
{{ partial "openapi/render-parameters" (dict "parameters" $simple_parameters "type" "query" "caption" "query parameters") }}
|
|
|
|
{{ end }}
|
|
|
|
{{ $body_parameters := where $parameters "in" "body"}}
|
|
{{ if $body_parameters }}
|
|
<h3>Request body</h3>
|
|
|
|
{{/* at most one body param is allowed by the spec */}}
|
|
{{ $body_parameter := index $body_parameters 0 }}
|
|
{{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body_parameter.schema "path" $path) }}
|
|
{{ $schema := partial "json-schema/resolve-allof" $schema }}
|
|
|
|
{{ $additional_types := partial "json-schema/resolve-additional-types" $schema }}
|
|
{{ $additional_types = uniq $additional_types }}
|
|
{{ range $additional_types }}
|
|
{{ partial "openapi/render-object-table" (dict "caption" .title "properties" .properties "required" .required "additionalProperties" .additionalProperties) }}
|
|
{{ end }}
|
|
|
|
<h3>Request body example</h3>
|
|
|
|
{{ $example := partial "json-schema/resolve-example" $schema }}
|
|
{{ $example_json := jsonify (dict "indent" " ") $example }}
|
|
{{ $example_json = replace $example_json "\\u003c" "<" }}
|
|
{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
|
|
|
|
```json
|
|
{{ $example_json }}
|
|
```
|
|
{{ end }}
|
|
|
|
{{ else }}
|
|
<p>No request parameters or request body.</p>
|
|
{{ end }}
|