From eb22fac5dc421eba7981840cadab2cf04e4e1a9f Mon Sep 17 00:00:00 2001
From: Travis Ralston <travisr@matrix.org>
Date: Thu, 21 Mar 2024 14:45:07 -0600
Subject: [PATCH] Break out non-JSON request/response content types as tables
 (#1756)

* Break out non-JSON request/response content types as tables

Currently we display this as a table like "image/png|image/jpeg" and description on a single line, but we're using a table. This breaks the join out to individual rows.

* changelog
---
 .../newsfragments/1756.clarification            |  1 +
 .../partials/openapi/render-content-type.html   | 17 ++++++++++-------
 layouts/partials/openapi/render-request.html    |  7 ++++---
 layouts/partials/openapi/render-responses.html  |  7 +++----
 4 files changed, 18 insertions(+), 14 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1756.clarification

diff --git a/changelogs/client_server/newsfragments/1756.clarification b/changelogs/client_server/newsfragments/1756.clarification
new file mode 100644
index 00000000..918e87c1
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1756.clarification
@@ -0,0 +1 @@
+Clearly indicate that each `Content-Type` may have distinct behaviour on non-JSON requests/responses.
diff --git a/layouts/partials/openapi/render-content-type.html b/layouts/partials/openapi/render-content-type.html
index da1a69bd..036522de 100644
--- a/layouts/partials/openapi/render-content-type.html
+++ b/layouts/partials/openapi/render-content-type.html
@@ -1,27 +1,30 @@
 {{/*
 
-  Render a table showing content type and description, given:
+  Render a table showing content types and their descriptions, given
+  two arrays with equal length:
 
-  * `content_type`: the content type as a string
+  * `content_types`: the content type strings
 
-  * `description`: the description as a string
+  * `descriptions`: the description strings
 
 */}}
 
-{{ $content_type := .content_type }}
-{{ $description := .description}}
+{{ $content_types := .content_types }}
+{{ $descriptions := .descriptions}}
 
-{{ if $content_type }}
+{{ if (gt (len $content_types) 0) }}
 
 <table class="content-type-table">
  <thead>
   <th class="col-name">Content-Type</th>
   <th class="col-description">Description</th>
  </thead>
+ {{ range $idx, $content_type := $content_types }}
  <tr>
   <td><code>{{ $content_type }}</code></td>
-  <td>{{ $description | markdownify -}}</td>
+  <td>{{ index $descriptions $idx | markdownify -}}</td>
  </tr>
+ {{ end }}
 </table>
 
 {{ end }}
diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html
index 5ef55c64..f41e062d 100644
--- a/layouts/partials/openapi/render-request.html
+++ b/layouts/partials/openapi/render-request.html
@@ -53,12 +53,13 @@
             {{/*
                 Show the content types and description.
             */}}
-            {{ $mimes := slice }}  
+            {{ $mimes := slice }}
+            {{ $descriptions := slice }}
             {{ range $mime, $body := $request_body.content }}
                 {{ $mimes = $mimes | append $mime }}
+                {{ $descriptions = $descriptions | append $request_body.description }}
             {{ end }}
-            {{ $content_type := delimit $mimes "|"}}
-            {{ partial "openapi/render-content-type" (dict "content_type" $content_type "description" $request_body.description) }}
+            {{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }}
         {{ end }}
 
 <h3>Request body example</h3>
diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html
index 82c2f954..dba7fa8b 100644
--- a/layouts/partials/openapi/render-responses.html
+++ b/layouts/partials/openapi/render-responses.html
@@ -109,13 +109,12 @@
                 Show the content types and description.
             */}}
             {{ $mimes := slice }}
-            {{ $desc := "" }}
+            {{ $descriptions := slice }}
             {{ range $mime, $body := $response.content }}
                 {{ $mimes = $mimes | append $mime }}
-                {{ $desc = $body.schema.description }}
+                {{ $descriptions = $descriptions | append $body.schema.description }}
             {{ end }}
-            {{ $content_type := delimit $mimes "|"}}
-            {{ partial "openapi/render-content-type" (dict "content_type" $content_type "description" $desc) }}
+            {{ partial "openapi/render-content-type" (dict "content_types" $mimes "descriptions" $descriptions) }}
         {{ end }}
     {{ end }}
 {{ end }}