Stop autogenerating examples where we already have one #1384
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
richvdh
commented
Dec 21, 2022
Comment on lines
210
to
-220
| 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" | ||
| } |
There was a problem hiding this comment.
this is so that we still get an example for auth.
Comment on lines
+78
to
+82
| "auth": { | ||
| "type": "example.type.foo", | ||
| "session": "xxxxx", | ||
| "example_credential": "verypoorsharedsecret" | ||
| }, |
There was a problem hiding this comment.
again, this means that we still get an example for auth.
Comment on lines
-15
to
-19
| example: { | ||
| "client_secret": "monkeys_are_GREAT", | ||
| "email": "foo@example.com", | ||
| "send_attempt": 1 | ||
| } |
There was a problem hiding this comment.
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.
Comment on lines
-15
to
-20
| example: { | ||
| "client_secret": "monkeys_are_GREAT", | ||
| "country": "GB", | ||
| "phone_number": "07700900001", | ||
| "send_attempt": 1 | ||
| } |
| @@ -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? | |||
dbkr
approved these changes
Dec 21, 2022
clokep
pushed a commit
to clokep/matrix-spec
that referenced
this pull request
May 3, 2023
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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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 viewer does, so we end up with examples being
inconsistent.
Preview: https://pr1384--matrix-spec-previews.netlify.app