From 3be746c9d3994760b47925fe3671112e787734c1 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>
Date: Tue, 4 Jan 2022 16:47:58 +0000
Subject: [PATCH] Fix rendering of response examples (#3584)

* Fix rendering of response examples

Fixes the autogeneration of JSON examples for array objects. This fixes a
number of "Specification error: Example invalid or not present" errors in the
rendered spec.

* Unbreak examples for non-objects/arrays

The previous change had broken auto-generated examples for everything that
wasn't an object or array; fix it up again.

* Remove conditions on $example

Everything should now have a generated example, so the condition is
redundant. Furthermore it was suppressing examples for APIs where the example
was an empty dict.
---
 .../partials/json-schema/resolve-example.html | 28 +++++++++++++++----
 layouts/partials/openapi/render-request.html  | 12 ++------
 .../partials/openapi/render-responses.html    | 12 ++------
 3 files changed, 29 insertions(+), 23 deletions(-)

diff --git a/layouts/partials/json-schema/resolve-example.html b/layouts/partials/json-schema/resolve-example.html
index 51ce6d53..90620b72 100644
--- a/layouts/partials/json-schema/resolve-example.html
+++ b/layouts/partials/json-schema/resolve-example.html
@@ -11,19 +11,37 @@
 
 {{ $this_object := partial "json-schema/resolve-allof" . }}
 
-{{ if eq $this_object.type "object" }}
+{{ $example := $this_object.example }}
 
-    {{ if not $this_object.example }}
-        {{ $this_object := merge (dict "example" dict ) $this_object }}
+{{ if eq $this_object.type "object" }}
+    {{ if not $example }}
+        {{ $example = dict }}
     {{ end }}
 
     {{ range $key, $property := $this_object.properties}}
         {{ $this_property_example := partial "json-schema/resolve-example" $property }}
         {{ if $this_property_example }}
-            {{ $this_object = merge (dict "example" (dict $key $this_property_example)) $this_object }}
+            {{ $example = merge (dict $key $this_property_example) $example }}
+        {{ end }}
+    {{ end }}
+
+{{ else if eq $this_object.type "array" }}
+
+    {{ if not $example }}
+        {{/* the "items" within an array can either be an object (where we have a
+             list of items which match the schema), or a list (for tuple
+             validation, where each item has a different schema).
+
+             TODO: support tuple validation here.
+        */}}
+        {{ if reflect.IsMap $this_object.items }}
+            {{ $items_example := partial "json-schema/resolve-example" $this_object.items }}
+            {{ $example = slice $items_example }}
+        {{ else }}
+            {{ $example = slice }}
         {{ end }}
     {{ end }}
 
 {{ end }}
 
-{{ return $this_object.example }}
+{{ return $example }}
diff --git a/layouts/partials/openapi/render-request.html b/layouts/partials/openapi/render-request.html
index 1695c2f8..5e801299 100644
--- a/layouts/partials/openapi/render-request.html
+++ b/layouts/partials/openapi/render-request.html
@@ -47,19 +47,13 @@
 <h3>Request body example</h3>
 
         {{ $example := partial "json-schema/resolve-example" $schema }}
-        {{ if $example }}
-            {{ $example_json := jsonify (dict "indent" "  ") $example }}
-            {{ $example_json = replace $example_json "\\u003c" "<" }}
-            {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
+        {{ $example_json := jsonify (dict "indent" "  ") $example }}
+        {{ $example_json = replace $example_json "\\u003c" "<" }}
+        {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
 
 ```json
 {{ $example_json }}
 ```
-
-        {{ else }}
-            {{ partial "alert" (dict "type" "warning" "omit_title" "true" "color" "warning" "content" "Specification error: Example invalid or not present") }}
-        {{ end }}
-
     {{ end }}
 
 {{ else }}
diff --git a/layouts/partials/openapi/render-responses.html b/layouts/partials/openapi/render-responses.html
index c92aba8e..350b0257 100644
--- a/layouts/partials/openapi/render-responses.html
+++ b/layouts/partials/openapi/render-responses.html
@@ -79,19 +79,13 @@
                 {{ $example = index $example "application/json" }}
             {{ end }}
 
-            {{ if $example }}
-                {{ $example_json := jsonify (dict "indent" "  ") $example }}
-                {{ $example_json = replace $example_json "\\u003c" "<" }}
-                {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
+            {{ $example_json := jsonify (dict "indent" "  ") $example }}
+            {{ $example_json = replace $example_json "\\u003c" "<" }}
+            {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
 
 ```json
 {{ $example_json }}
 ```
-
-            {{ else }}
-                {{ partial "alert" (dict "type" "warning" "omit_title" "true" "color" "warning" "content" "Specification error: Example invalid or not present") }}
-            {{ end }}
-
         {{ end }}
     {{ end }}
 {{ end }}