From c3a4f5b1098fc82b694559bfa053cac531a65062 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?K=C3=A9vin=20Commaille?= Date: Tue, 9 May 2023 16:24:43 +0200 Subject: [PATCH] Manual fixes to API files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Kévin Commaille --- .../appservice_room_directory.yaml | 3 + data/api/client-server/content-repo.yaml | 93 +++++-------------- .../client-server/definitions/push_rule.yaml | 6 +- data/api/client-server/device_management.yaml | 2 +- data/api/client-server/inviting.yaml | 2 + data/api/client-server/joining.yaml | 2 - data/api/client-server/keys.yaml | 11 +++ data/api/client-server/knocking.yaml | 2 - data/api/client-server/peeking_events.yaml | 2 + data/api/client-server/presence.yaml | 5 +- data/api/client-server/profile.yaml | 4 +- data/api/client-server/pusher.yaml | 3 +- data/api/client-server/pushrules.yaml | 4 +- data/api/client-server/receipts.yaml | 2 +- data/api/client-server/registration.yaml | 2 + data/api/client-server/relations.yaml | 8 ++ data/api/client-server/rooms.yaml | 3 + data/api/client-server/typing.yaml | 2 +- data/api/identity/v2_terms.yaml | 1 + data/api/push-gateway/push_notifier.yaml | 2 +- data/api/server-server/backfill.yaml | 2 - .../definitions/unsigned_pdu_base.yaml | 58 ++++++------ data/api/server-server/invites-v1.yaml | 16 ++++ data/api/server-server/invites-v2.yaml | 19 ++++ data/api/server-server/joins-v1.yaml | 20 ++-- data/api/server-server/joins-v2.yaml | 19 ++-- data/api/server-server/keys_query.yaml | 2 +- data/api/server-server/knocks.yaml | 17 +++- data/api/server-server/leaving-v1.yaml | 11 +++ data/api/server-server/leaving-v2.yaml | 12 +++ data/api/server-server/public_rooms.yaml | 1 + .../api/server-server/third_party_invite.yaml | 24 +++++ data/api/server-server/user_keys.yaml | 3 + 33 files changed, 226 insertions(+), 137 deletions(-) diff --git a/data/api/client-server/appservice_room_directory.yaml b/data/api/client-server/appservice_room_directory.yaml index 98a81953..2af58a22 100644 --- a/data/api/client-server/appservice_room_directory.yaml +++ b/data/api/client-server/appservice_room_directory.yaml @@ -67,6 +67,7 @@ paths: - visibility required: true security: + # again, this is the appservice's token - not a typical client's - accessToken: [] responses: "200": @@ -94,4 +95,6 @@ servers: default: /_matrix/client/v3 components: securitySchemes: + # Note: this is the same access_token definition used elsewhere in the client + # server API, however this expects an access token for an application service. $ref: definitions/security.yaml diff --git a/data/api/client-server/content-repo.yaml b/data/api/client-server/content-repo.yaml index c7e202e9..3678f782 100644 --- a/data/api/client-server/content-repo.yaml +++ b/data/api/client-server/content-repo.yaml @@ -38,12 +38,7 @@ paths: type: string requestBody: content: - application/json: - schema: - type: string - example: - format: byte - "*/*": + application/octet-stream: schema: type: string example: @@ -146,12 +141,7 @@ paths: type: string requestBody: content: - application/json: - schema: - type: string - example: - format: byte - "*/*": + application/octet-stream: schema: type: string example: @@ -168,9 +158,6 @@ paths: examples: response: value: {} - "*/*": - schema: - type: object "403": description: |- The user does not have permission to upload the content. Some reasons for this error include: @@ -192,9 +179,6 @@ paths: "errcode": "M_FORBIDDEN", "error": "Cannot upload this content" } - "*/*": - schema: - $ref: definitions/errors/error.yaml "409": description: |- The endpoint was called with a media ID that already has content. A @@ -210,9 +194,6 @@ paths: "errcode": "M_CANNOT_OVERWRITE_MEDIA", "error": "Media already uploaded" } - "*/*": - schema: - $ref: definitions/errors/error.yaml "413": description: The uploaded content is too large for the server. content: @@ -225,18 +206,12 @@ paths: "errcode": "M_TOO_LARGE", "error": "Cannot upload files larger than 100mb" } - "*/*": - schema: - $ref: definitions/errors/error.yaml "429": description: This request was rate-limited. content: application/json: schema: $ref: definitions/errors/rate_limited.yaml - "*/*": - schema: - $ref: definitions/errors/rate_limited.yaml tags: - Media /media/v1/create: @@ -266,6 +241,8 @@ paths: x-addedInMatrixVersion: "1.7" security: - accessToken: [] + # empty json object + parameters: [] responses: "200": description: The [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris) for @@ -371,24 +348,23 @@ paths: schema: type: string content: - "*/*": + application/octet-stream: schema: type: string + # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the uploaded file." - format: binary "429": description: This request was rate-limited. content: - "*/*": + application/json: schema: $ref: definitions/errors/rate_limited.yaml "502": description: The content is too large for the server to serve. content: - "*/*": + application/json: schema: $ref: definitions/errors/error.yaml - application/json: examples: response: value: { @@ -400,10 +376,9 @@ paths: The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_NOT_YET_UPLOADED`. content: - "*/*": + application/json: schema: $ref: definitions/errors/error.yaml - application/json: examples: response: value: { @@ -485,24 +460,24 @@ paths: schema: type: string content: - "*/*": + application/octet-stream: schema: type: string + # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the uploaded file." format: binary "429": description: This request was rate-limited. content: - "*/*": + application/json: schema: $ref: definitions/errors/rate_limited.yaml "502": description: The content is too large for the server to serve. content: - "*/*": + application/json: schema: $ref: definitions/errors/error.yaml - application/json: examples: response: value: { @@ -514,10 +489,9 @@ paths: The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_NOT_YET_UPLOADED`. content: - "*/*": + application/json: schema: $ref: definitions/errors/error.yaml - application/json: examples: response: value: { @@ -620,11 +594,13 @@ paths: image/jpeg: schema: type: string + # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the thumbnail." format: binary image/png: schema: type: string + # This is a workaround for us not being able to say the response is required. description: "**Required.** The bytes for the thumbnail." format: binary "400": @@ -633,13 +609,9 @@ paths: the content. For example, the client requested non-integer dimensions or asked for negatively-sized images. content: - image/jpeg: - schema: - $ref: definitions/errors/error.yaml - image/png: - schema: - $ref: definitions/errors/error.yaml application/json: + schema: + $ref: definitions/errors/error.yaml examples: response: value: { @@ -649,13 +621,9 @@ paths: "413": description: The local content is too large for the server to thumbnail. content: - image/jpeg: - schema: - $ref: definitions/errors/error.yaml - image/png: - schema: - $ref: definitions/errors/error.yaml application/json: + schema: + $ref: definitions/errors/error.yaml examples: response: value: { @@ -665,22 +633,15 @@ paths: "429": description: This request was rate-limited. content: - image/jpeg: - schema: - $ref: definitions/errors/rate_limited.yaml - image/png: + application/json: schema: $ref: definitions/errors/rate_limited.yaml "502": description: The remote content is too large for the server to thumbnail. content: - image/jpeg: - schema: - $ref: definitions/errors/error.yaml - image/png: - schema: - $ref: definitions/errors/error.yaml application/json: + schema: + $ref: definitions/errors/error.yaml examples: response: value: { @@ -692,13 +653,9 @@ paths: The content is not yet available. A [standard error response](/client-server-api/#standard-error-response) will be returned with the `errcode` `M_NOT_YET_UPLOADED`. content: - image/jpeg: - schema: - $ref: definitions/errors/error.yaml - image/png: - schema: - $ref: definitions/errors/error.yaml application/json: + schema: + $ref: definitions/errors/error.yaml examples: response: value: { diff --git a/data/api/client-server/definitions/push_rule.yaml b/data/api/client-server/definitions/push_rule.yaml index 94a9d320..4f1b41ad 100644 --- a/data/api/client-server/definitions/push_rule.yaml +++ b/data/api/client-server/definitions/push_rule.yaml @@ -17,9 +17,9 @@ type: object properties: actions: items: - type: - - object - - string + oneOf: + - type: object + - type: string type: array description: |- The actions to perform when this rule is matched. diff --git a/data/api/client-server/device_management.yaml b/data/api/client-server/device_management.yaml index 9ae3f557..32d3db9a 100644 --- a/data/api/client-server/device_management.yaml +++ b/data/api/client-server/device_management.yaml @@ -124,7 +124,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object examples: response: value: {} diff --git a/data/api/client-server/inviting.yaml b/data/api/client-server/inviting.yaml index 4c373c77..ce5d503d 100644 --- a/data/api/client-server/inviting.yaml +++ b/data/api/client-server/inviting.yaml @@ -16,6 +16,8 @@ info: title: Matrix Client-Server Room Joining API version: 1.0.0 paths: + # With an extra " " to disambiguate from the 3pid invite endpoint + # The extra space makes it sort first for what I'm sure is a good reason. "/rooms/{roomId}/invite ": post: summary: Invite a user to participate in a particular room. diff --git a/data/api/client-server/joining.yaml b/data/api/client-server/joining.yaml index 35f56cac..020c5a0e 100644 --- a/data/api/client-server/joining.yaml +++ b/data/api/client-server/joining.yaml @@ -143,8 +143,6 @@ paths: example: - matrix.org - elsewhere.ca - style: form - explode: false schema: type: array items: diff --git a/data/api/client-server/keys.yaml b/data/api/client-server/keys.yaml index 3f6bc806..cb8a11db 100644 --- a/data/api/client-server/keys.yaml +++ b/data/api/client-server/keys.yaml @@ -38,6 +38,10 @@ paths: allOf: - $ref: definitions/device_keys.yaml one_time_keys: + # $ref: "definitions/one_time_keys.yaml" + # XXX: We can't define an actual object here, so we have to hope + # that people will look at the swagger source or can figure it out + # from the other endpoints/example. type: object title: OneTimeKeys description: |- @@ -61,6 +65,8 @@ paths: ed25519:JLAFKJWSCS: IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA fallback_keys: x-addedInMatrixVersion: "1.2" + # $ref: "definitions/one_time_keys.yaml" + # XXX: We can't define an actual object here - see above. type: object title: OneTimeKeys description: |- @@ -346,6 +352,11 @@ paths: additionalProperties: type: object additionalProperties: + # $ref: "definitions/one_time_keys.yaml" + # XXX: We can't define an actual object here, so we have to hope + # that people will read the link provided in the description + # and figure it out from the other endpoints/example. + # See also one_time_key parameter for /keys/upload above. type: object title: OneTimeKeys example: diff --git a/data/api/client-server/knocking.yaml b/data/api/client-server/knocking.yaml index f8f16b48..b778f02b 100644 --- a/data/api/client-server/knocking.yaml +++ b/data/api/client-server/knocking.yaml @@ -55,8 +55,6 @@ paths: example: - matrix.org - elsewhere.ca - style: form - explode: false schema: type: array items: diff --git a/data/api/client-server/peeking_events.yaml b/data/api/client-server/peeking_events.yaml index 6ed44b79..19eb67a0 100644 --- a/data/api/client-server/peeking_events.yaml +++ b/data/api/client-server/peeking_events.yaml @@ -16,6 +16,8 @@ info: title: Matrix Client-Server Sync Guest API version: 1.0.0 paths: + # With an extra " " to disambiguate from the getEvents endpoint + # The extra space makes it sort first for what I'm sure is a good reason. "/events ": get: summary: Listen on the event stream of a particular room. diff --git a/data/api/client-server/presence.yaml b/data/api/client-server/presence.yaml index 4deda9e0..caa19854 100644 --- a/data/api/client-server/presence.yaml +++ b/data/api/client-server/presence.yaml @@ -65,7 +65,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object examples: response: value: {} @@ -113,8 +113,7 @@ paths: by this user. status_msg: description: The state message for this user if one was set. - nullable: true - type: string + type: ["string", "null"] currently_active: type: boolean description: Whether the user is currently active diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml index 17d0d1b9..b47cf591 100644 --- a/data/api/client-server/profile.yaml +++ b/data/api/client-server/profile.yaml @@ -53,7 +53,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object examples: response: value: {} @@ -139,7 +139,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object examples: response: value: {} diff --git a/data/api/client-server/pusher.yaml b/data/api/client-server/pusher.yaml index 10110475..c686e9ae 100644 --- a/data/api/client-server/pusher.yaml +++ b/data/api/client-server/pusher.yaml @@ -174,8 +174,7 @@ paths: The kind of pusher to configure. `"http"` makes a pusher that sends HTTP pokes. `"email"` makes a pusher that emails the user with unread notifications. `null` deletes the pusher. - nullable: true - type: string + type: ["string", "null"] app_id: type: string description: |- diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml index 32812a2a..77a07afd 100644 --- a/data/api/client-server/pushrules.yaml +++ b/data/api/client-server/pushrules.yaml @@ -350,7 +350,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object examples: response: value: {} @@ -487,7 +487,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object examples: response: value: {} diff --git a/data/api/client-server/receipts.yaml b/data/api/client-server/receipts.yaml index 279cdda1..abbd7a62 100644 --- a/data/api/client-server/receipts.yaml +++ b/data/api/client-server/receipts.yaml @@ -89,7 +89,7 @@ paths: application/json: schema: type: object - maxProperties: 0 + maxProperties: 0 # empty json object examples: response: value: {} diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index d961ac17..1f823ac8 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -66,6 +66,8 @@ paths: name: kind required: false description: The kind of account to register. Defaults to `user`. + # swagger-UI overrides the default with the example, so better make the + # example the default. example: user schema: type: string diff --git a/data/api/client-server/relations.yaml b/data/api/client-server/relations.yaml index f773c39b..65c3491a 100644 --- a/data/api/client-server/relations.yaml +++ b/data/api/client-server/relations.yaml @@ -97,6 +97,8 @@ paths: - b - f responses: + # note: this endpoint deliberately does not support rate limiting, therefore a + # 429 error response is not included. "200": description: |- The paginated child events which point to the parent. If no events are @@ -161,6 +163,7 @@ paths: } tags: - Event relationships + # The same as above, with added `/{relType}` "/rooms/{roomId}/relations/{eventId}/{relType}": get: summary: Get the child events for a given parent event, with a given `relType`. @@ -251,6 +254,8 @@ paths: - b - f responses: + # note: this endpoint deliberately does not support rate limiting, therefore a + # 429 error response is not included. "200": description: |- The paginated child events which point to the parent. If no events are @@ -317,6 +322,7 @@ paths: } tags: - Event relationships + # The same as above, with added `/{eventType}` "/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}": get: summary: Get the child events for a given parent event, with a given `relType` @@ -419,6 +425,8 @@ paths: - b - f responses: + # note: this endpoint deliberately does not support rate limiting, therefore a + # 429 error response is not included. "200": description: |- The paginated child events which point to the parent. If no events are diff --git a/data/api/client-server/rooms.yaml b/data/api/client-server/rooms.yaml index 15a0fea1..4a192305 100644 --- a/data/api/client-server/rooms.yaml +++ b/data/api/client-server/rooms.yaml @@ -200,6 +200,9 @@ paths: example: YWxsCgpOb25lLDM1ODcwOA schema: type: string + # XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON + # filter might be a better alternative. + # See https://github.com/matrix-org/matrix-doc/issues/1337 - in: query name: membership description: |- diff --git a/data/api/client-server/typing.yaml b/data/api/client-server/typing.yaml index 4e53cf69..6d6a7437 100644 --- a/data/api/client-server/typing.yaml +++ b/data/api/client-server/typing.yaml @@ -70,7 +70,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object examples: response: value: {} diff --git a/data/api/identity/v2_terms.yaml b/data/api/identity/v2_terms.yaml index 03568882..f4a45932 100644 --- a/data/api/identity/v2_terms.yaml +++ b/data/api/identity/v2_terms.yaml @@ -52,6 +52,7 @@ paths: might be and could be "alpha", semantically versioned, or arbitrary. required: - version + # TODO: TravisR - Make this render additionalProperties: type: object title: Internationalised Policy diff --git a/data/api/push-gateway/push_notifier.yaml b/data/api/push-gateway/push_notifier.yaml index c64011d2..e23d33b0 100644 --- a/data/api/push-gateway/push_notifier.yaml +++ b/data/api/push-gateway/push_notifier.yaml @@ -202,7 +202,7 @@ paths: content: application/json: schema: - type: object + type: object # empty json object properties: rejected: type: array diff --git a/data/api/server-server/backfill.yaml b/data/api/server-server/backfill.yaml index 9d82edc7..a37e5ed4 100644 --- a/data/api/server-server/backfill.yaml +++ b/data/api/server-server/backfill.yaml @@ -40,8 +40,6 @@ paths: required: true example: - $abc123:matrix.org - style: form - explode: false schema: type: array items: diff --git a/data/api/server-server/definitions/unsigned_pdu_base.yaml b/data/api/server-server/definitions/unsigned_pdu_base.yaml index 20a3e83d..c21149f6 100644 --- a/data/api/server-server/definitions/unsigned_pdu_base.yaml +++ b/data/api/server-server/definitions/unsigned_pdu_base.yaml @@ -56,20 +56,21 @@ properties: maxItems: 2 minItems: 2 items: - - type: string - title: Event ID - example: "$abc123:matrix.org" - - type: object - title: Event Hash - example: { - "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" - } - properties: - sha256: - type: string - description: The event hash. - example: Base64EncodedSha256HashesShouldBe43BytesLong - required: ['sha256'] + anyOf: + - type: string + title: Event ID + example: "$abc123:matrix.org" + - type: object + title: Event Hash + example: { + "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" + } + properties: + sha256: + type: string + description: The event hash. + example: Base64EncodedSha256HashesShouldBe43BytesLong + required: ['sha256'] depth: type: integer description: |- @@ -91,20 +92,21 @@ properties: maxItems: 2 minItems: 2 items: - - type: string - title: Event ID - example: "$abc123:matrix.org" - - type: object - title: Event Hash - example: { - "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" - } - properties: - sha256: - type: string - description: The event hash. - example: Base64EncodedSha256HashesShouldBe43BytesLong - required: ['sha256'] + anyOf: + - type: string + title: Event ID + example: "$abc123:matrix.org" + - type: object + title: Event Hash + example: { + "sha256": "Base64EncodedSha256HashesShouldBe43BytesLong" + } + properties: + sha256: + type: string + description: The event hash. + example: Base64EncodedSha256HashesShouldBe43BytesLong + required: ['sha256'] redacts: type: string description: For redaction events, the ID of the event being redacted. diff --git a/data/api/server-server/invites-v1.yaml b/data/api/server-server/invites-v1.yaml index 78a24b49..270682d9 100644 --- a/data/api/server-server/invites-v1.yaml +++ b/data/api/server-server/invites-v1.yaml @@ -75,6 +75,22 @@ paths: example: $ref: ../../event-schemas/examples/invite_room_state.json type: object + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@joe:elsewhere.com", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "invite" + }, + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + } + } required: true responses: "200": diff --git a/data/api/server-server/invites-v2.yaml b/data/api/server-server/invites-v2.yaml index 5006a188..91dfca3a 100644 --- a/data/api/server-server/invites-v2.yaml +++ b/data/api/server-server/invites-v2.yaml @@ -78,6 +78,25 @@ paths: required: - room_version - event + example: { + "room_version": "2", + "event": { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@joe:elsewhere.com", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "invite" + }, + "signatures": { + "example.com": { + "ed25519:key_version": "SomeSignatureHere" + }, + } + } + } required: true responses: "200": diff --git a/data/api/server-server/joins-v1.yaml b/data/api/server-server/joins-v1.yaml index 01638152..35b20e61 100644 --- a/data/api/server-server/joins-v1.yaml +++ b/data/api/server-server/joins-v1.yaml @@ -49,8 +49,6 @@ paths: example: - "1" - "2" - style: form - explode: false schema: type: array items: @@ -321,6 +319,18 @@ paths: - origin_server_ts - type - content + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "join", + "join_authorised_via_users_server": "@anyone:resident.example.org" + } + } required: true responses: "200": @@ -356,9 +366,6 @@ paths: description: |- The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: object - properties: {} state: type: array description: |- @@ -372,9 +379,6 @@ paths: description: |- The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending on the room version - check the [room version specification](/rooms) for precise event formats. - schema: - type: object - properties: {} required: - auth_chain - state diff --git a/data/api/server-server/joins-v2.yaml b/data/api/server-server/joins-v2.yaml index d4f26cca..32819193 100644 --- a/data/api/server-server/joins-v2.yaml +++ b/data/api/server-server/joins-v2.yaml @@ -17,6 +17,7 @@ info: title: Matrix Federation Join Room API version: 1.0.0 paths: + # Note: there is no v2 of make_join (yet) "/send_join/{roomId}/{eventId}": put: summary: Submit a signed join event to a resident server @@ -138,6 +139,18 @@ paths: - origin_server_ts - type - content + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "join", + "join_authorised_via_users_server": "@anyone:resident.example.org" + } + } required: true responses: "200": @@ -171,9 +184,6 @@ paths: items: type: object title: PDU - schema: - type: object - properties: {} x-changedInMatrixVersion: "1.6": |- reworded to include only consider state events returned in @@ -190,9 +200,6 @@ paths: items: type: object title: PDU - schema: - type: object - properties: {} x-changedInMatrixVersion: "1.6": permit omission of membership events. event: diff --git a/data/api/server-server/keys_query.yaml b/data/api/server-server/keys_query.yaml index b639a2a8..096cc5a6 100644 --- a/data/api/server-server/keys_query.yaml +++ b/data/api/server-server/keys_query.yaml @@ -88,7 +88,7 @@ paths: given. additionalProperties: type: object - name: ServerName + title: ServerName description: The server names to query. additionalProperties: type: object diff --git a/data/api/server-server/knocks.yaml b/data/api/server-server/knocks.yaml index bab56d95..266e3368 100644 --- a/data/api/server-server/knocks.yaml +++ b/data/api/server-server/knocks.yaml @@ -44,12 +44,10 @@ paths: - in: query name: ver description: The room versions the sending server has support for. - required: true + required: true # knocking was supported in v7 example: - "1" - "7" - style: form - explode: false schema: type: array items: @@ -121,7 +119,7 @@ paths: - content - sender required: - - room_version + - room_version # knocking was added in v7 - event examples: response: @@ -273,6 +271,17 @@ paths: - origin_server_ts - type - content + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "knock" + } + } required: true responses: "200": diff --git a/data/api/server-server/leaving-v1.yaml b/data/api/server-server/leaving-v1.yaml index c339cc03..a6c82987 100644 --- a/data/api/server-server/leaving-v1.yaml +++ b/data/api/server-server/leaving-v1.yaml @@ -222,6 +222,17 @@ paths: - type - depth - content + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "leave" + } + } required: true responses: "200": diff --git a/data/api/server-server/leaving-v2.yaml b/data/api/server-server/leaving-v2.yaml index 6701c7c1..75248b53 100644 --- a/data/api/server-server/leaving-v2.yaml +++ b/data/api/server-server/leaving-v2.yaml @@ -17,6 +17,7 @@ info: title: Matrix Federation Leave Room API version: 1.0.0 paths: + # Note: there is no v2 of make_leave (yet) "/send_leave/{roomId}/{eventId}": put: summary: Submit a signed leave event to a resident server @@ -107,6 +108,17 @@ paths: - type - depth - content + example: { + "room_id": "!somewhere:example.org", + "type": "m.room.member", + "state_key": "@someone:example.org", + "origin": "example.org", + "origin_server_ts": 1549041175876, + "sender": "@someone:example.org", + "content": { + "membership": "leave" + } + } required: true responses: "200": diff --git a/data/api/server-server/public_rooms.yaml b/data/api/server-server/public_rooms.yaml index 4e0c7a1f..dd909f8f 100644 --- a/data/api/server-server/public_rooms.yaml +++ b/data/api/server-server/public_rooms.yaml @@ -159,6 +159,7 @@ paths: - $ref: ../client-server/definitions/public_rooms_chunk.yaml - type: object properties: + # Override description of join_rule join_rule: type: string description: |- diff --git a/data/api/server-server/third_party_invite.yaml b/data/api/server-server/third_party_invite.yaml index ff8ba3ca..3eac4811 100644 --- a/data/api/server-server/third_party_invite.yaml +++ b/data/api/server-server/third_party_invite.yaml @@ -151,6 +151,27 @@ paths: - sender - state_key - content + example: { + "type": "m.room.member", + "room_id": "!abc123:matrix.org", + "sender": "@joe:matrix.org", + "state_key": "@someone:example.org", + "content": { + "membership": "invite", + "third_party_invite": { + "display_name": "alice", + "signed": { + "mxid": "@alice:localhost", + "token": "abc123", + "signatures": { + "magic.forest": { + "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg" + } + } + } + } + } + } description: A partial `m.room.member` event required: true responses: @@ -225,6 +246,8 @@ paths: type: string description: The user ID that sent the invite. example: "@bob:matrix.org" + # TODO (TravisR): Make this reusable when doing IS spec changes + # also make sure it isn't lying about anything, like the key version signed: type: object title: Identity Server Signatures @@ -240,6 +263,7 @@ paths: example: "@alice:matrix.org" token: type: string + # TODO: What is this actually? description: A token. example: Hello World signatures: diff --git a/data/api/server-server/user_keys.yaml b/data/api/server-server/user_keys.yaml index b823a31e..60995a74 100644 --- a/data/api/server-server/user_keys.yaml +++ b/data/api/server-server/user_keys.yaml @@ -63,10 +63,13 @@ paths: See the [Client-Server Key Algorithms](/client-server-api/#key-algorithms) section for more information on the Key Object format. + # User additionalProperties: type: object + # Device additionalProperties: type: object + # Key additionalProperties: type: object title: KeyObject