archive
/
matrix-spec
mirror of https://github.com/matrix-org/matrix-spec
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Render binary request and response bodies (#1579)

Browse Source 
Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>
pull/1585/head
Kévin Commaille 1 year ago committed by GitHub
parent 4a9bda9bed
commit 564444d43e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 140 additions and 76 deletions
Show Stats Download Patch File Download Diff File

2
assets/scss/custom.scss
Unescape Escape View File

@ -374,7 +374,7 @@ footer {
padding: 1rem; padding: 1rem;
} }
&.object-table, &.response-table { &.object-table, &.response-table, &.content-type-table {
border: 1px $table-border-color solid; border: 1px $table-border-color solid;
caption { caption {

1
changelogs/client_server/newsfragments/1579.clarification
Unescape Escape View File

@ -0,0 +1 @@
Render binary request and response bodies.

2
data/api/client-server/account-data.yaml
Unescape Escape View File

@ -327,6 +327,8 @@ paths:
`M_INVALID_PARAM`." `M_INVALID_PARAM`."
content: content:
application/json: application/json:
schema:
$ref: ../client-server/definitions/errors/error.yaml
examples: examples:
response: response:
value: { value: {

18
data/api/client-server/content-repo.yaml
Unescape Escape View File

@ -39,10 +39,7 @@ paths:
requestBody: requestBody:
content: content:
application/octet-stream: application/octet-stream:
schema: example: <bytes>
type: string
example: <bytes>
format: byte
description: The content to be uploaded. description: The content to be uploaded.
required: true required: true
responses: responses:
@ -142,10 +139,7 @@ paths:
requestBody: requestBody:
content: content:
application/octet-stream: application/octet-stream:
schema: example: <bytes>
type: string
example: <bytes>
format: byte
description: The content to be uploaded. description: The content to be uploaded.
required: true required: true
responses: responses:
@ -361,10 +355,8 @@ paths:
content: content:
application/octet-stream: application/octet-stream:
schema: schema:
type: string
# This is a workaround for us not being able to say the response is required. # This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the uploaded file." description: "**Required.** The bytes for the uploaded file."
format: binary
"307": "307":
description: A redirect to the thumbnail of the requested content. description: A redirect to the thumbnail of the requested content.
headers: headers:
@ -500,10 +492,8 @@ paths:
content: content:
application/octet-stream: application/octet-stream:
schema: schema:
type: string
# This is a workaround for us not being able to say the response is required. # This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the uploaded file." description: "**Required.** The bytes for the uploaded file."
format: binary
"307": "307":
description: A redirect to the thumbnail of the requested content. description: A redirect to the thumbnail of the requested content.
headers: headers:
@ -657,15 +647,11 @@ paths:
content: content:
image/jpeg: image/jpeg:
schema: schema:
type: string
# This is a workaround for us not being able to say the response is required. # This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the thumbnail." description: "**Required.** The bytes for the thumbnail."
format: binary
image/png: image/png:
schema: schema:
type: string
description: "**Required.** The bytes for the thumbnail." description: "**Required.** The bytes for the thumbnail."
format: binary
"307": "307":
description: A redirect to the thumbnail of the requested content. description: A redirect to the thumbnail of the requested content.
headers: headers:

27
layouts/partials/openapi/render-content-type.html
Unescape Escape View File

@ -0,0 +1,27 @@
{{/*
Render a table showing content type and description, given:
* `content_type`: the content type as a string
* `description`: the description as a string
*/}}
{{ $content_type := .content_type }}
{{ $description := .description}}
{{ if $content_type }}
<table class="content-type-table">
<thead>
<th class="col-name">Content-Type</th>
<th class="col-description">Description</th>
</thead>
<tr>
<td><code>{{ $content_type }}</code></td>
<td>{{ $description | markdownify -}}</td>
</tr>
</table>
{{ end }}

51
layouts/partials/openapi/render-request.html
Unescape Escape View File

@ -35,10 +35,13 @@
{{ if $request_body }} {{ if $request_body }}
<h3>Request body</h3> <h3>Request body</h3>
{{/* {{/*
A request can have several content types. Only show the schema for JSON. A request can have several content types.
*/}} */}}
{{ $json_body := index $request_body.content "application/json" }} {{ $json_body := index $request_body.content "application/json" }}
{{ if $json_body }} {{ if $json_body }}
{{/*
Display the JSON schemas
*/}}
{{ $schema := partial "json-schema/resolve-refs" (dict "schema" $json_body.schema "path" $path) }} {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $json_body.schema "path" $path) }}
{{ $schema := partial "json-schema/resolve-allof" $schema }} {{ $schema := partial "json-schema/resolve-allof" $schema }}
@ -47,6 +50,16 @@
{{ range $additional_types }} {{ range $additional_types }}
{{ partial "openapi/render-object-table" . }} {{ partial "openapi/render-object-table" . }}
{{ end }} {{ end }}
{{ else }}
{{/*
Show the content types and description.
*/}}
{{ $mimes := slice }}
{{ range $mime, $body := $request_body.content }}
{{ $mimes = $mimes | append $mime }}
{{ end }}
{{ $content_type := delimit $mimes "|"}}
{{ partial "openapi/render-content-type" (dict "content_type" $content_type "description" $request_body.description) }}
{{ end }} {{ end }}
<h3>Request body example</h3> <h3>Request body example</h3>
@ -54,17 +67,41 @@
Show all the examples. Show all the examples.
*/}} */}}
{{ range $mime, $body := $request_body.content }} {{ range $mime, $body := $request_body.content }}
{{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body.schema "path" $path) }} {{ $example := dict }}
{{ $schema := partial "json-schema/resolve-allof" $schema }}
{{ if $body.schema }}
{{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body.schema "path" $path) }}
{{ $schema := partial "json-schema/resolve-allof" $schema }}
{{ $example = partial "json-schema/resolve-example" $schema }}
{{ end }}
{{ $example := partial "json-schema/resolve-example" $schema }} {{ if and (eq ($example | len) 0) $body.example }}
{{ $example_json := jsonify (dict "indent" " ") $example }} {{/*
{{ $example_json = replace $example_json "\\u003c" "<" }} If no example was generated from the schema, fallback to the
{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} main example.
*/}}
{{ $example = $body.example }}
{{ end }}
{{ if eq $mime "application/json" }}
{{ $example_json := jsonify (dict "indent" " ") $example }}
{{ $example_json = replace $example_json "\\u003c" "<" }}
{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
```json ```json
{{ $example_json }} {{ $example_json }}
``` ```
{{ else }}
{{ $example = $example | safeHTML }}
{{/*
We need to set a language for the code otherwise the styling
is different than other examples.
*/}}
```json
{{ $example }}
```
{{ end }}
{{ end }} {{ end }}
{{ end }} {{ end }}

115
layouts/partials/openapi/render-responses.html
Unescape Escape View File

@ -38,73 +38,84 @@
</table> </table>
{{ range $code, $response := $responses }} {{ range $code, $response := $responses }}
{{/* {{ if $response.content }}
A response can have several content types so only insert the title once.
*/}}
{{ $is_title_set := false }}
{{ range $content_type, $content := $response.content }}
{{ if $content.schema }}
{{ if not $is_title_set }}
{{ $is_title_set = true }}
<h3>{{$code}} response</h3> <h3>{{$code}} response</h3>
{{ end }}
{{ $schema := partial "json-schema/resolve-refs" (dict "schema" $content.schema "path" $path) }}
{{ $schema := partial "json-schema/resolve-allof" $schema }}
{{/* {{/*
All this is to work out how to express the content of the response A response can have several content types.
in the case where it is an array.
*/}} */}}
{{ if eq $schema.type "array" }} {{ $json_body := index $response.content "application/json" }}
{{ $type_of := "" }} {{ if $json_body }}
{{ if $schema.items.anyOf }} {{/*
{{ $types := slice }} Display the JSON schemas
{{ range $schema.items.anyOf }} */}}
{{ if .title }}
{{ $types = $types | append .title}} {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $json_body.schema "path" $path) }}
{{ else }} {{ $schema := partial "json-schema/resolve-allof" $schema }}
{{ $types = $types | append .type }}
{{/*
All this is to work out how to express the content of the response
in the case where it is an array.
*/}}
{{ if eq $schema.type "array" }}
{{ $type_of := "" }}
{{ if $schema.items.anyOf }}
{{ $types := slice }}
{{ range $schema.items.anyOf }}
{{ if .title }}
{{ $types = $types | append .title}}
{{ else }}
{{ $types = $types | append .type }}
{{ end }}
{{ end }} {{ end }}
{{ $type_of = delimit $types ", "}}
{{ else }}
{{ $type_of = $schema.items.title }}
{{ end }} {{ end }}
{{ $type_of = delimit $types ", "}}
{{ else }}
{{ $type_of = $schema.items.title }}
{{ end }}
<p>Array of <code>{{ $type_of }}</code>.</p> <p>Array of <code>{{ $type_of }}</code>.</p>
{{ end }} {{ end }}
{{/* {{/*
render object tables for any objects referenced in the render object tables for any objects referenced in the
response. (This will be a no-op for response types which aren't response. (This will be a no-op for response types which aren't
objects or arrays.) objects or arrays.)
*/}} */}}
{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }} {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }}
{{ $additional_types = uniq $additional_types }} {{ $additional_types = uniq $additional_types }}
{{ range $additional_types }} {{ range $additional_types }}
{{ partial "openapi/render-object-table" . }} {{ partial "openapi/render-object-table" . }}
{{ end }}
{{/*
render an example. currently this is only supported for arrays and objects.
*/}}
{{ if or (eq $schema.type "object") (eq $schema.type "array") }}
{{ $example := partial "json-schema/resolve-example" $schema }}
{{ if $content.examples }}
{{ $example = partial "json-schema/resolve-refs" (dict "schema" $content.examples "path" $path) }}
{{ $example = $example.response.value }}
{{ end }} {{ end }}
{{ $example_json := jsonify (dict "indent" " ") $example }} {{/*
{{ $example_json = replace $example_json "\\u003c" "<" }} render an example. currently this is only supported for arrays and objects.
{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }} */}}
{{ if or (eq $schema.type "object") (eq $schema.type "array") }}
{{ $example := partial "json-schema/resolve-example" $schema }}
{{ if $json_body.examples }}
{{ $example = partial "json-schema/resolve-refs" (dict "schema" $json_body.examples "path" $path) }}
{{ $example = $example.response.value }}
{{ end }}
{{ $example_json := jsonify (dict "indent" " ") $example }}
{{ $example_json = replace $example_json "\\u003c" "<" }}
{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
```json ```json
{{ $example_json }} {{ $example_json }}
``` ```
{{ end }} {{ end }}
{{ else }}
{{/*
Show the content types and description.
*/}}
{{ $mimes := slice }}
{{ $desc := "" }}
{{ range $mime, $body := $response.content }}
{{ $mimes = $mimes | append $mime }}
{{ $desc = $body.schema.description }}
{{ end }}
{{ $content_type := delimit $mimes "|"}}
{{ partial "openapi/render-content-type" (dict "content_type" $content_type "description" $desc) }}
{{ end }} {{ end }}
{{ end }} {{ end }}
{{ end }} {{ end }}

Write Preview
Loading…
Cancel
Save