Stop autogenerating examples where we already have one (#1384)

If an object definition already has an example, we shouldn't try to extend that
definition by adding examples derived from the individual properties. Doing so
is confusing, and there is no way to inhibit it when it is not desired. It's
also not what the RapiDoc viewere does, so we end up with examples being
inconsistent.

changelogs/internal/newsfragments/1384.clarification

@@ -0,0 +1 @@
+Stop autogenerating examples where we already have an example.

data/api/client-server/administrative_contact.yaml

@@ -210,14 +210,12 @@ paths:
               client_secret:
                 type: string
                 description: The client secret used in the session with the homeserver.
+                example: "d0nt-T3ll"
               sid:
                 type: string
                 description: The session identifier given by the homeserver.
+                example: "abc123987"
             required: ["client_secret",  "sid"]
-            example: {
-              "sid": "abc123987",
-              "client_secret": "d0nt-T3ll"
-            }
       responses:
         200:
           description: The addition was successful.

data/api/client-server/cross_signing.yaml

@@ -75,6 +75,11 @@ paths:
                 allOf:
                 - $ref: "definitions/auth_data.yaml"
             example: {
+              "auth": {
+                "type": "example.type.foo",
+                "session": "xxxxx",
+                "example_credential": "verypoorsharedsecret"
+              },
               "master_key": {
                 "user_id": "@alice:example.com",
                 "usage": ["master"],

data/api/identity/definitions/request_email_validation.yaml

@@ -12,11 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 type: object
-example: {
-  "client_secret": "monkeys_are_GREAT",
-  "email": "foo@example.com",
-  "send_attempt": 1
-}
 properties:
   client_secret:
     type: string

data/api/identity/definitions/request_msisdn_validation.yaml

@@ -12,12 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 type: object
-example: {
-  "client_secret": "monkeys_are_GREAT",
-  "country": "GB",
-  "phone_number": "07700900001",
-  "send_attempt": 1
-}
 properties:
   client_secret:
     type: string

data/api/server-server/user_devices.yaml

@@ -88,7 +88,6 @@ paths:
                   The user\'s master cross-signing key.
                 allOf:
                   - $ref: ../client-server/definitions/cross_signing_key.yaml
-                  # FIXME: why isn't the doc generator picking up this example?
                   - example: {
                       "user_id": "@alice:example.com",
                       "usage": ["master"],
@@ -102,7 +101,6 @@ paths:
                   The user\'s self-signing key.
                 allOf:
                   - $ref: ../client-server/definitions/cross_signing_key.yaml
-                  # FIXME: why isn't the doc generator picking up this example?
                   - example: {
                       "user_id": "@alice:example.com",
                       "usage": ["self_signing"],

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

@@ -13,21 +13,20 @@
 
 {{ $example := $this_object.example }}
 
-{{ if eq $this_object.type "object" }}
+{{ if not $example }}
-    {{ if not $example }}
+
+    {{ if eq $this_object.type "object" }}
         {{ $example = dict }}
-    {{ end }}
 
-    {{ range $key, $property := $this_object.properties}}
+        {{ range $key, $property := $this_object.properties}}
-        {{ $this_property_example := partial "json-schema/resolve-example" $property }}
+            {{ $this_property_example := partial "json-schema/resolve-example" $property }}
-        {{ if $this_property_example }}
+            {{ if $this_property_example }}
-            {{ $example = merge (dict $key $this_property_example) $example }}
+                {{ $example = merge (dict $key $this_property_example) $example }}
+            {{ end }}
         {{ end }}
-    {{ end }}
 
-{{ else if eq $this_object.type "array" }}
+    {{ 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).