You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/layouts/partials/openapi/render-responses.html

136 lines
4.7 KiB
HTML

{{/*
Render the response part of a single HTTP API operation, given:
* `responses`: OpenAPI data specifying the responses
* `anchor_base`: a prefix to add to the HTML anchors generated for each object
This template renders:
* a summary of all the different responses
* details of the body for each response code
* body parameters, which may be more complex, containing nested objects
* response body examples
*/}}
{{ $responses := .responses }}
{{ $anchor_base := .anchor_base }}
<h2>Responses</h2>
<table class="response-table">
<thead>
<tr>
<th class="col-status">Status</th>
<th class="col-status-description">Description</th>
</tr>
</thead>
{{ range $code, $response := $responses }}
<tr>
<td><code>{{ $code }}</code></td>
<td>{{ $response.description | markdownify }}</td>
</tr>
{{ end }}
</table>
{{ range $code, $response := $responses }}
{{ if $response.content }}
<h3>{{$code}} response</h3>
{{/* Display defined headers */}}
{{ if $response.headers }}
{{/* build a dict mapping from name->schema, which render-object-table expects */}}
{{ $headers_dict := dict }}
{{ range $header_name,$header_props := $response.headers }}
{{/*
merge the schema at the same level as the rest of the other fields because that is
what `render-object-table` expects. Put the schema first so examples in it are
overwritten.
*/}}
{{ $header_schema := merge $header_props.schema $header_props }}
{{ $headers_dict = merge $headers_dict (dict $header_name $header_schema )}}
{{ end }}
{{/* and render the headers */}}
{{ partial "openapi/render-object-table" (dict "title" "Headers" "properties" $headers_dict) }}
{{ end }}
{{/*
A response can have several content types.
*/}}
{{ $json_body := index $response.content "application/json" }}
{{ if $json_body }}
{{/*
Display the JSON schemas
*/}}
{{ $schema := $json_body.schema }}
{{/*
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 }}
{{ $type_of = delimit $types ", "}}
{{ else }}
{{ $type_of = $schema.items.title }}
{{ end }}
<p>Array of <code>{{ $type_of }}</code>.</p>
{{ end }}
{{/*
render object tables for any objects referenced in the
response. (This will be a no-op for response types which aren't
objects or arrays.)
*/}}
{{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor_base) }}
{{ range $additional_types }}
{{ 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 $json_body.examples }}
{{ $example = $json_body.examples.response.value }}
{{ end }}
{{ $example_json := jsonify (dict "indent" " ") $example }}
{{ $example_json = replace $example_json "\\u003c" "<" }}
{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
```json
{{ $example_json }}
```
{{ end }}
{{ else }}
{{/*
Show the content types and description.
*/}}
{{ $mimes := slice }}
{{ $descriptions := slice }}
{{ range $mime, $body := $response.content }}
{{ $mimes = $mimes | append $mime }}
{{ $descriptions = $descriptions | append $body.schema.description }}
{{ end }}
{{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }}
{{ end }}
{{ end }}
{{ end }}