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
matrix-org · Mar 21, 2024 · eb22fac · eb22fac
1 parent 6700f5d
commit eb22fac
Show file tree

Hide file tree

Showing 4 changed files with 18 additions and 14 deletions.
diff --git a/changelogs/client_server/newsfragments/1756.clarification 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
@@ -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
@@ -53,12 +53,13 @@ <h3>Request body</h3>
             {{/*
                 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
@@ -109,13 +109,12 @@ <h3>{{$code}} response</h3>
                 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 }}