Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Stop autogenerating examples where we already have one #1384

Merged
merged 1 commit into from Dec 21, 2022
Merged

Stop autogenerating examples where we already have one #1384

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/internal/newsfragments/1384.clarification
View file
Open in desktop
@@ -0,0 +1 @@
Stop autogenerating examples where we already have an example.
6 changes: 2 additions & 4 deletions data/api/client-server/administrative_contact.yaml
View file
Open in desktop
Expand Up @@ -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"
}
Comment on lines 210 to -220
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is so that we still get an example for auth.

responses:
200:
description: The addition was successful.
Expand Down
5 changes: 5 additions & 0 deletions data/api/client-server/cross_signing.yaml
View file
Open in desktop
Expand Up @@ -75,6 +75,11 @@ paths:
allOf:
- $ref: "definitions/auth_data.yaml"
example: {
"auth": {
"type": "example.type.foo",
"session": "xxxxx",
"example_credential": "verypoorsharedsecret"
},
Comment on lines +78 to +82
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

again, this means that we still get an example for auth.

"master_key": {
"user_id": "@alice:example.com",
"usage": ["master"],
Expand Down
5 changes: 0 additions & 5 deletions data/api/identity/definitions/request_email_validation.yaml
View file
Open in desktop
Expand Up @@ -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
}
Comment on lines -15 to -19
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is redundant (the individual fields all have examples), but also, this object is inherited elsewhere and this example was overriding the examples for the fields in the derived object.

properties:
client_secret:
type: string
Expand Down
6 changes: 0 additions & 6 deletions data/api/identity/definitions/request_msisdn_validation.yaml
View file
Open in desktop
Expand Up @@ -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
}
Comment on lines -15 to -20
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ditto

properties:
client_secret:
type: string
Expand Down
2 changes: 0 additions & 2 deletions data/api/server-server/user_devices.yaml
View file
Open in desktop
Expand Up @@ -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?
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... this was why.

- example: {
"user_id": "@alice:example.com",
"usage": ["master"],
Expand All @@ -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"],
Expand Down
19 changes: 9 additions & 10 deletions layouts/partials/json-schema/resolve-example.html
View file
Open in desktop
Expand Up @@ -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).
Expand Down