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.

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

layouts/partials/openapi/render-request.html

@@ -47,7 +47,6 @@
 <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 }}
@@ -55,11 +54,6 @@
 ```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 }}

layouts/partials/openapi/render-responses.html

@@ -79,7 +79,6 @@
                 {{ $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 }}
@@ -87,11 +86,6 @@
 ```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 }}