Stop autogenerating examples where we already have one (matrix-org#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.
clokep · May 3, 2023 · 860a56a · 860a56a
1 parent 3fb3cab
commit 860a56a
Show file tree

Hide file tree

Showing 7 changed files with 17 additions and 27 deletions.
diff --git a/changelogs/internal/newsfragments/1384.clarification b/changelogs/internal/newsfragments/1384.clarification
@@ -0,0 +1 @@
+Stop autogenerating examples where we already have an example.
diff --git a/data/api/client-server/administrative_contact.yaml b/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.

diff --git a/data/api/client-server/cross_signing.yaml b/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"],

diff --git a/data/api/identity/definitions/request_email_validation.yaml b/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

diff --git a/data/api/identity/definitions/request_msisdn_validation.yaml b/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

diff --git a/data/api/server-server/user_devices.yaml b/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"],

diff --git a/layouts/partials/json-schema/resolve-example.html b/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}}
-        {{ $this_property_example := partial "json-schema/resolve-example" $property }}
-        {{ if $this_property_example }}
-            {{ $example = merge (dict $key $this_property_example) $example }}
+        {{ 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 }}
-    {{ 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).