Support finding several examples in JSON schema

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

layouts/partials/json-schema/resolve-example.html

@@ -1,46 +0,0 @@
-{{/*
-
-  For complex objects, example content is sometimes attached to the
-  object's individual properties (and subproperties...), so to get
-  a complete example for the whole object we need to iterate through
-  its properties (and subproperties...) and assemble them.
-
-  That's what this template does.
-
-*/}}
-
-{{ $this_object := . }}
-
-{{ $example := $this_object.example }}
-
-{{ if not $example }}
-
-    {{ if eq $this_object.type "object" }}
-        {{ $example = dict }}
-
-        {{ range $key, $property := $this_object.properties}}
-            {{ $this_property_example := partial "json-schema/resolve-example" $property }}
-            {{ if $this_property_example }}
-                {{ $example = merge (dict $key $this_property_example) $example }}
-            {{ end }}
-        {{ end }}
-
-    {{ else if eq $this_object.type "array" }}
-
-        {{/* 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 }}
-            {{ if $items_example }}
-                {{ $example = slice $items_example }}
-            {{ end }}
-        {{ end }}
-    {{ end }}
-
-{{ end }}
-
-{{ return $example }}

layouts/partials/json-schema/resolve-examples.html

@@ -0,0 +1,64 @@
+{{/*
+    
+    Find examples in the given JSON schema.
+
+    Tries to find examples in the `examples` and `example` keys of the schema
+    first.
+
+    If it doesn't succeed, iterates through the properties and subproperties to
+    collect their examples, to merge them into a complete example for the  whole
+    object.
+
+    Parameter: the JSON schema to extract the examples from.
+
+*/}}
+
+{{ $this_object := . }}
+{{ $examples := slice }}
+
+{{ if $this_object.examples }}
+    {{/* This is an array of examples, we can just use it */}}
+    {{ $examples = $this_object.examples }}
+{{ else if $this_object.example }}
+    {{ $examples = slice $this_object.example }}
+{{ else }}
+    {{/* Resolve the nested examples */}}
+    {{ if eq $this_object.type "object" }}
+        {{ $example := dict }}
+
+        {{ range $key, $property := $this_object.properties}}
+            {{ $this_property_examples := partial "json-schema/resolve-examples" $property }}
+            {{/*
+                It would be too complex to handle several nested examples,
+                just use the first one.
+            */}}
+            {{ with index $this_property_examples 0 }}
+                {{ $example = merge (dict $key .) $example }}
+            {{ end }}
+        {{ end }}
+
+        {{ $examples = slice $example }}
+
+    {{ else if eq $this_object.type "array" }}
+
+        {{/* 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_examples := partial "json-schema/resolve-examples" $this_object.items }}
+            {{/*
+                It would be too complex to handle several nested examples,
+                just use the first one.
+            */}}
+            {{ with index $items_examples 0 }}
+                {{ $examples = slice (slice .) }}
+            {{ end }}
+        {{ end }}
+    {{ end }}
+
+{{ end }}
+
+{{ return $examples }}

layouts/partials/openapi/render-request.html

@@ -59,21 +59,23 @@
             Show all the examples.
         */}}
         {{ range $mime, $body := $request_body.content }}
-            {{ $example := dict }}
+            {{ $examples := slice }}
 
             {{ if $body.schema }}
-                {{ $example = partial "json-schema/resolve-example" $body.schema }}
+                {{ $examples = partial "json-schema/resolve-examples" $body.schema }}
             {{ end }}
 
-            {{ if and (eq ($example | len) 0) $body.example }}
+            {{ if and (eq ($examples | len) 0) $body.example }}
                 {{/*
-                    If no example was generated from the schema, fallback to the
+                    If no examples were generated from the schema, fallback to the
                     main example.
                 */}}
-                {{ $example = $body.example }}
+                {{ $examples = slice $body.example }}
             {{ end }}
 
-            {{ partial "render-example" (dict "example" $example "mime" $mime) }}
+            {{ range $examples }}
+                {{ partial "render-example" (dict "example" . "mime" $mime) }}
+            {{ end }}
         {{ end }}
     {{ end }}
 

layouts/partials/openapi/render-responses.html

@@ -104,15 +104,20 @@
             {{ end }}
 
             {{/*
-            render an example. currently this is only supported for arrays and objects.
+                Render the examples. Currently this is only supported for arrays
+                and objects.
             */}}
             {{ if or (eq $schema.type "object") (eq $schema.type "array") }}
-                {{ $example := partial "json-schema/resolve-example" $schema }}
+                {{ $examples := slice }}
                 {{ if $json_body.examples }}
-                    {{ $example = $json_body.examples.response.value }}
+                    {{ $examples = slice $json_body.examples.response.value }}
+                {{ else }}
+                    {{ $examples = partial "json-schema/resolve-examples" $schema }}
                 {{ end }}
 
-                {{ partial "render-example" (dict "example" $example) }}
+                {{ range $examples }}
+                    {{ partial "render-example" (dict "example" .) }}
+                {{ end }}
             {{ end }}
         {{  else }}
             {{/*

layouts/shortcodes/definition.html

@@ -60,8 +60,10 @@
 
 <h2>Examples</h2>
 
-{{ $example := partial "json-schema/resolve-example" $definition }}
+{{ $examples := partial "json-schema/resolve-examples" $definition }}
-{{ partial "render-example" (dict "example" $example) }}
+{{ range $examples }}
+    {{ partial "render-example" (dict "example" .) }}
+{{ end }}
 
 </details>