matrix-spec/layouts/partials/openapi/render-responses.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 }}
        {{ $anchor := printf "%s_response-%s" $anchor_base $code }}
<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) }}
            {{ 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.
            */}}
            {{ partial "openapi/render-content-type" (dict "content_types" $response.content) }}
        {{ end }}
    {{ end }}
{{ end }}