Render binary request and response bodies (#1579)

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

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
         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
         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 @@
     {{ 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,6 +50,16 @@
             {{ 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>
@@ -54,17 +67,41 @@
             Show all the examples.
         */}}
         {{ range $mime, $body := $request_body.content }}
+            {{ $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 }}
+                {{ $example = partial "json-schema/resolve-example" $schema }}
+            {{ end }}
+
+            {{ 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,19 +38,18 @@
 </table>
 
 {{ 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>
-            {{ end }}
+        {{/*
+            A response can have several content types.
+        */}}
+        {{ $json_body := index $response.content "application/json" }}
+        {{ if $json_body }}
+            {{/*
+                Display the JSON schemas
+            */}}
 
-        {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $content.schema "path" $path) }}
+            {{ $schema := partial "json-schema/resolve-refs" (dict "schema" $json_body.schema "path" $path) }}
             {{ $schema := partial "json-schema/resolve-allof" $schema }}
 
             {{/*
@@ -92,8 +91,8 @@
             */}}
             {{ if or (eq $schema.type "object") (eq $schema.type "array") }}
                 {{ $example := partial "json-schema/resolve-example" $schema }}
-            {{ if $content.examples }}
+                {{ if $json_body.examples }}
-                {{ $example = partial "json-schema/resolve-refs" (dict "schema" $content.examples "path" $path) }}
+                    {{ $example = partial "json-schema/resolve-refs" (dict "schema" $json_body.examples "path" $path) }}
                     {{ $example = $example.response.value }}
                 {{ end }}
 
@@ -105,6 +104,18 @@
 {{ $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 }}