From 7bd48ca9c72ccb5685a15f67ebd13fcc99083d66 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Wed, 21 Dec 2022 16:24:11 +0000 Subject: [PATCH] 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. --- .../internal/newsfragments/1384.clarification | 1 + .../client-server/administrative_contact.yaml | 6 ++---- data/api/client-server/cross_signing.yaml | 5 +++++ .../definitions/request_email_validation.yaml | 5 ----- .../request_msisdn_validation.yaml | 6 ------ data/api/server-server/user_devices.yaml | 2 -- .../partials/json-schema/resolve-example.html | 19 +++++++++---------- 7 files changed, 17 insertions(+), 27 deletions(-) create mode 100644 changelogs/internal/newsfragments/1384.clarification diff --git a/changelogs/internal/newsfragments/1384.clarification b/changelogs/internal/newsfragments/1384.clarification new file mode 100644 index 000000000..46c5f9f0b --- /dev/null +++ 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 index e2e782aa5..8bee761f5 100644 --- 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 index b88da999a..0ac32cfb7 100644 --- 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 index c8a3af6a3..a447c8710 100644 --- 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 index 2b1c87080..28544580d 100644 --- 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 index 9fb15777f..1c127f9b1 100644 --- 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 index 90620b720..ef626afd4 100644 --- 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).