Render binary request and response bodies

assets/scss/custom.scss

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

changelogs/client_server/newsfragments/1579.clarification

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

data/api/client-server/account-data.yaml

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

data/api/client-server/content-repo.yaml

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

layouts/partials/openapi/render-content-type.html

@@ -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 }}

layouts/partials/openapi/render-request.html

@@ -35,10 +35,13 @@ <h3>Request parameters</h3>
     {{ if $request_body }}
 <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" }}
         {{ 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-allof" $schema }}
 
@@ -47,24 +50,58 @@ <h3>Request body</h3>
             {{ range $additional_types }}
                 {{ partial "openapi/render-object-table" . }}
             {{ 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 }}
 
 <h3>Request body example</h3>
         {{/*
             Show all the examples.
         */}}
         {{ range $mime, $body := $request_body.content }}
-            {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $body.schema "path" $path) }}
-            {{ $schema := partial "json-schema/resolve-allof" $schema }}
+            {{ $example := dict }}
+
+            {{ 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 }}
-            {{ $example_json := jsonify (dict "indent" "  ") $example }}
-            {{ $example_json = replace $example_json "\\u003c" "<" }}
-            {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
+            {{ if and (eq ($example | len) 0) $body.example }}
+                {{/*
+                    If no example was generated from the schema, fallback to the
+                    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
 {{ $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 }}
 

layouts/partials/openapi/render-responses.html

@@ -38,73 +38,84 @@ <h2>Responses</h2>
 </table>
 
 {{ range $code, $response := $responses }}
-    {{/*
-        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 }}
+    {{ if $response.content }}
 <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
-          in the case where it is an array.
+            A response can have several content types.
         */}}
-        {{ 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 }}
+        {{ $json_body := index $response.content "application/json" }}
+        {{ 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-allof" $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 }}
-                {{ $type_of = delimit $types ", "}}
-            {{ else }}
-                {{ $type_of = $schema.items.title }}
-            {{ end }}
 <p>Array of <code>{{ $type_of }}</code>.</p>
-        {{ end }}
+            {{ 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) }}
-        {{ $additional_types = uniq $additional_types }}
-        {{ 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 $content.examples }}
-                {{ $example = partial "json-schema/resolve-refs" (dict "schema" $content.examples "path" $path) }}
-                {{ $example = $example.response.value }}
+            {{/*
+            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) }}
+            {{ $additional_types = uniq $additional_types }}
+            {{ range $additional_types }}
+                {{ partial "openapi/render-object-table" . }}
             {{ end }}
 
-            {{ $example_json := jsonify (dict "indent" "  ") $example }}
-            {{ $example_json = replace $example_json "\\u003c" "<" }}
-            {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
+            {{/*
+            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 = 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
 {{ $example_json }}
 ```
             {{ 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 }}