Look for examples in all possible locations (#2076)

We used to only look for examples in a few (sometimes arbitrary) places, and we didn't support showing several examples in most cases. This is intended to fix this. In the process we try to deduplicate code to make sure that we use the same logic everywhere.

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

changelogs/internal/newsfragments/2076.clarification

@@ -0,0 +1 @@
+Support more locations for examples in OpenAPI definitions and JSON schemas.

changelogs/server_server/newsfragments/2076.clarification

@@ -0,0 +1 @@
+Remove an erroneous `room_id` field in a few examples.

data/api/server-server/invites-v1.yaml

@@ -75,22 +75,6 @@ paths:
                           example:
                             $ref: ../../event-schemas/examples/invite_room_state.json
               type: object
-            example: {
-              "room_id": "!somewhere:example.org",
-              "type": "m.room.member",
-              "state_key": "@joe:elsewhere.com",
-              "origin": "example.org",
-              "origin_server_ts": 1549041175876,
-              "sender": "@someone:example.org",
-              "content": {
-                  "membership": "invite"
-              },
-              "signatures": {
-                "example.com": {
-                  "ed25519:key_version": "SomeSignatureHere"
-                },
-              }
-            }
         required: true
       responses:
         "200":

data/api/server-server/invites-v2.yaml

@@ -78,25 +78,6 @@ paths:
               required:
                 - room_version
                 - event
-            example: {
-              "room_version": "2",
-              "event": {
-                "room_id": "!somewhere:example.org",
-                "type": "m.room.member",
-                "state_key": "@joe:elsewhere.com",
-                "origin": "example.org",
-                "origin_server_ts": 1549041175876,
-                "sender": "@someone:example.org",
-                "content": {
-                    "membership": "invite"
-                },
-                "signatures": {
-                  "example.com": {
-                    "ed25519:key_version": "SomeSignatureHere"
-                  },
-                }
-              }
-            }
         required: true
       responses:
         "200":

data/api/server-server/joins-v2.yaml

@@ -140,7 +140,6 @@ paths:
                 - type
                 - content
             example: {
-              "room_id": "!somewhere:example.org",
               "type": "m.room.member",
               "state_key": "@someone:example.org",
               "origin": "example.org",

data/api/server-server/knocks.yaml

@@ -270,7 +270,6 @@ paths:
                 - type
                 - content
             example: {
-              "room_id": "!somewhere:example.org",
               "type": "m.room.member",
               "state_key": "@someone:example.org",
               "origin": "example.org",

layouts/partials/events/example.html

@@ -13,10 +13,4 @@
 {{ $path := delimit (slice "event-schemas/examples" .name) "/" }}
 
 {{ $example_content := partial "json-schema/resolve-refs" (dict "schema" .schema "path" $path) }}
-{{ $example_json := jsonify (dict "indent" "  ") $example_content }}
+{{ partial "render-example" (dict "example" $example_content) }}
-{{ $example_json = replace $example_json "\\u003c" "<" }}
-{{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
-
-```json
-{{ $example_json }}
-```

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,71 @@
+{{/*
+    
+    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 }}
+
+        {{/*
+            Add the assembled example to the list if either (a) the example is
+            non-empty, or (b) the object itself is meant to be empty (so an
+            empty example is correct).
+        */}}
+        {{ if (or $example (not $this_object.properties)) }}
+            {{ $examples = slice $example }}
+        {{ 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_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-media-type-objects.html

@@ -0,0 +1,104 @@
+{{/*
+
+  Render a map of [Media Type Objects](https://spec.openapis.org/oas/v3.1.1#media-type-object).
+  This map can be found as the `content` field of requests and responses.
+
+  Parameters:
+
+  * `content`: A map of MIME type to Media Type Object
+  * `kind`: the kind of object that is rendered, either `request` or `response`.
+  * `anchor_base`: a prefix to add to the HTML anchors generated for each object
+
+  This template renders:
+
+  * Object tables if the map contains an `application/json` MIME type, or a
+    table with the MIME types and the corresponding description of the object.
+  * The examples of the Media Type Objects.
+
+*/}}
+
+{{/*
+    Request and response bodies can have several content types. If there is a
+    JSON type, we display that; otherwise we just show the content types and
+    descriptions.
+*/}}
+{{ $json_body := index .content "application/json" }}
+{{ if $json_body }}
+    {{/*
+        Display the JSON schemas
+    */}}
+
+    {{ $schema := $json_body.schema }}
+
+    {{/*
+        All this is to work out how to express the content of the response
+        in the case where it is an array.
+    */}}
+    {{ if eq $schema.type "array" }}
+        {{ $type_of := "" }}
+        {{ if $schema.items.anyOf }}
+            {{ $types := slice }}
+            {{ range $schema.items.anyOf }}
+                {{ if .title }}
+                    {{ $types = $types | append .title}}
+                {{ else }}
+                    {{ $types = $types | append .type }}
+                {{ end }}
+            {{ end }}
+            {{ $type_of = delimit $types ", "}}
+        {{ else }}
+            {{ $type_of = $schema.items.title }}
+        {{ end }}
+<p>Array of <code>{{ $type_of }}</code>.</p>
+    {{ end }}
+
+    {{/*
+        Render object tables for any objects referenced in the request/response.
+        
+        This will be a no-op for request/response body types which aren't
+        objects or arrays.
+    */}}
+    {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" .anchor_base) }}
+    {{ range $additional_types }}
+        {{ partial "openapi/render-object-table" . }}
+    {{ end }}
+{{  else }}
+    {{/*
+        Show the content types and description.
+    */}}
+    {{ partial "openapi/render-content-type" (dict "content_types" .content) }}
+{{ end }}
+
+{{/*
+    Show all the examples.
+*/}}
+{{ if eq .kind "request" }}
+<h3>Request body example</h3>
+{{ end }}
+
+{{ range $mime, $body := .content }}
+    {{ $examples := slice }}
+
+    {{/*
+        Find the examples to display, with the following priority:
+
+        1. The `examples` field
+        2. The `example` field
+        3. The examples in the `schema` field
+    */}}
+    {{ if $body.examples }}
+        {{/* This is a map of string to Example Object */}}
+        {{ range $key, $example := $body.examples }}
+            {{/* The example is in the `value` field of the object */}}
+            {{ $examples = $examples | append (slice $example.value) }}
+        {{ end }}
+    {{ else if $body.example }}
+        {{ $examples = slice $body.example }}
+    {{ else if $body.schema }}
+        {{ $examples = partial "json-schema/resolve-examples" $body.schema }}
+    {{ end }}
+
+    {{ range $examples }}
+        {{ partial "render-example" (dict "example" . "mime" $mime) }}
+    {{ end }}
+{{ end }}

layouts/partials/openapi/render-request.html

@@ -33,65 +33,8 @@
 
     {{ if $request_body }}
 <h3>Request body</h3>
-        {{/*
-            A request can have several content types.
-        */}}
-        {{ $json_body := index $request_body.content "application/json" }}
-        {{ if $json_body }}
-            {{/*
-                Display the JSON schemas
-            */}}
-            {{ $schema := $json_body.schema }}
 
-            {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }}
+        {{ partial "openapi/render-media-type-objects" (dict "content" $request_body.content "kind" "request" "anchor_base" $anchor) }}
-            {{ range $additional_types }}
-                {{ partial "openapi/render-object-table" . }}
-            {{ end }}
-        {{ else }}
-            {{/*
-                Show the content types and description.
-            */}}
-            {{ partial "openapi/render-content-type" (dict "content_types" $request_body.content) }}
-        {{ end }}
-
-<h3>Request body example</h3>
-        {{/*
-            Show all the examples.
-        */}}
-        {{ range $mime, $body := $request_body.content }}
-            {{ $example := dict }}
-
-            {{ if $body.schema }}
-                {{ $example = partial "json-schema/resolve-example" $body.schema }}
-            {{ end }}
-
-            {{ if and (eq ($example | len) 0) $body.example }}
-                {{/*
-                    If no example was generated from the schema, fallback to the
-                    main example.
-                */}}
-                {{ $example = $body.example }}
-            {{ end }}
-
-            {{ if eq $mime "application/json" }}
-                {{ $example_json := jsonify (dict "indent" "  ") $example }}
-                {{ $example_json = replace $example_json "\\u003c" "<" }}
-                {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
-```json
-{{ $example_json }}
-```
-            {{ else }}
-                {{ $example = $example | safeHTML }}
-                {{/*
-                    We need to set a language for the code otherwise the styling
-                    is different than other examples.
-                */}}
-```json
-{{ $example }}
-```
-            {{ end }}
-
-        {{ end }}
     {{ end }}
 
 {{ else }}

layouts/partials/openapi/render-responses.html

@@ -59,72 +59,6 @@
             {{ partial "openapi/render-object-table" (dict "title" "Headers" "properties" $headers_dict) }}
         {{ end }}
 
-        {{/*
+        {{ partial "openapi/render-media-type-objects" (dict "content" $response.content "kind" "response" "anchor_base" $anchor) }}
-            A response can have several content types.
-        */}}
-        {{ $json_body := index $response.content "application/json" }}
-        {{ if $json_body }}
-            {{/*
-                Display the JSON schemas
-            */}}
-
-            {{ $schema := $json_body.schema }}
-
-            {{/*
-            All this is to work out how to express the content of the response
-            in the case where it is an array.
-            */}}
-            {{ if eq $schema.type "array" }}
-                {{ $type_of := "" }}
-                {{ if $schema.items.anyOf }}
-                    {{ $types := slice }}
-                    {{ range $schema.items.anyOf }}
-                        {{ if .title }}
-                            {{ $types = $types | append .title}}
-                        {{ else }}
-                            {{ $types = $types | append .type }}
-                        {{ end }}
-                    {{ end }}
-                    {{ $type_of = delimit $types ", "}}
-                {{ else }}
-                    {{ $type_of = $schema.items.title }}
-                {{ end }}
-<p>Array of <code>{{ $type_of }}</code>.</p>
-            {{ end }}
-
-
-            {{/*
-            render object tables for any objects referenced in the
-            response. (This will be a no-op for response types which aren't
-            objects or arrays.)
-            */}}
-            {{ $additional_types := partial "json-schema/resolve-additional-types" (dict "schema" $schema "anchor_base" $anchor) }}
-            {{ range $additional_types }}
-                {{ partial "openapi/render-object-table" . }}
-            {{ end }}
-
-            {{/*
-            render an example. 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 }}
-                {{ if $json_body.examples }}
-                    {{ $example = $json_body.examples.response.value }}
-                {{ end }}
-
-                {{ $example_json := jsonify (dict "indent" "  ") $example }}
-                {{ $example_json = replace $example_json "\\u003c" "<" }}
-                {{ $example_json = replace $example_json "\\u003e" ">" | safeHTML }}
-
-```json
-{{ $example_json }}
-```
-            {{ end }}
-        {{  else }}
-            {{/*
-                Show the content types and description.
-            */}}
-            {{ partial "openapi/render-content-type" (dict "content_types" $response.content) }}
-        {{ end }}
     {{ end }}
 {{ end }}

layouts/partials/render-example.html

@@ -0,0 +1,40 @@
+{{/*
+
+    Renders an example to be included in HTML, with support for pretty-printing
+    JSON.
+
+    Parameters:
+
+    * `example`: the example
+    * `mime`: the mime type of the example. Used to pretty-print JSON and for
+      syntax highlighting. If it is not provided, it is assumed to be
+      `application/json`.
+
+*/}}
+
+{{ $example := .example }}
+
+{{/*
+    We need to convert the mime type to a recognized language.
+    For simplicity we only support JSON, which is also the default. Other mime
+    types are not highlighted.
+*/}}
+{{ $language := "json" }}
+
+{{ if (and .mime (ne .mime "application/json")) }}
+    {{/*
+        `no-highlight` treats the value as plain text, but still styles the code
+        block like the ones with proper syntax highlighting.
+    */}}
+    {{ $language = "no-highlight" }}
+{{ end }}
+
+{{ if eq $language "json" }}
+    {{ $example = jsonify (dict "indent" "  ") $example }}
+    {{ $example = replace $example "\\u003c" "<" }}
+    {{ $example = replace $example "\\u003e" ">" }}
+{{ end }}
+
+```{{ $language }}
+{{ $example | safeHTML }}
+```

layouts/shortcodes/definition.html

@@ -58,13 +58,14 @@
     {{ partial "openapi/render-object-table" . }}
 {{end}}
 
+{{ $examples := partial "json-schema/resolve-examples" $definition }}
+{{ if $examples }}
 <h2>Examples</h2>
 
-{{ $example := partial "json-schema/resolve-example" $definition }}
+    {{ range $examples }}
-
+        {{ partial "render-example" (dict "example" .) }}
-```json
+    {{ end }}
-{{ jsonify (dict "indent" "  ") $example }}
+{{ end }}
-```
 
 </details>