diff --git a/api/server-server/definitions/invite_event.yaml b/api/server-server/definitions/invite_event.yaml index d87a1daac..9cef80611 100644 --- a/api/server-server/definitions/invite_event.yaml +++ b/api/server-server/definitions/invite_event.yaml @@ -23,43 +23,43 @@ allOf: type: string # TODO: Verify/clarify this - it doesn't seem right, given this is a 'regular' invite description: |- - The matrix ID of the user who sent the original ``m.room.third_party_invite`` + The matrix ID of the user who sent the original ``m.room.third_party_invite``. example: "@someone:example.org" origin: type: string - description: The name of the inviting homeserver + description: The name of the inviting homeserver. example: "matrix.org" origin_server_ts: type: integer format: int64 - description: A timestamp added by the inviting homeserver + description: A timestamp added by the inviting homeserver. example: 1234567890 type: type: string - description: The value ``m.room.member`` + description: The value ``m.room.member``. example: "m.room.member" state_key: type: string - description: The user ID of the invited member + description: The user ID of the invited member. example: "@joe:elsewhere.com" content: type: object title: Membership Event Content description: |- The content of the event, matching what is available in the - `Client-Server API`_ + `Client-Server API`_. example: {"membership": "invite"} properties: membership: type: string - description: The value ``invite`` + description: The value ``invite``. example: "invite" required: ['membership'] auth_events: type: array description: |- An event reference list containing the authorization events that would - allow the member to be invited to the room + allow the member to be invited to the room. items: type: array maxItems: 2 @@ -76,12 +76,12 @@ allOf: properties: sha256: type: string - description: The event hash + description: The event hash. example: abase64encodedsha256hashshouldbe43byteslong required: ['sha256'] redacts: type: string - description: Not used + description: Not used. required: # Every other field is already flagged as required by the $ref - state_key diff --git a/api/server-server/invites.yaml b/api/server-server/invites.yaml index d176a5aed..a5d21938e 100644 --- a/api/server-server/invites.yaml +++ b/api/server-server/invites.yaml @@ -35,13 +35,13 @@ paths: - in: path name: roomId type: string - description: The room ID that the user is being invited to + description: The room ID that the user is being invited to. required: true x-example: "!abc123:matrix.org" - in: path name: eventId type: string - description: The event ID for the invite event + description: The event ID for the invite event. required: true x-example: "$abc123:example.org" - in: body @@ -70,7 +70,7 @@ paths: maxItems: 2 items: - type: integer - description: The value ``200`` + description: The value ``200``. example: 200 - $ref: "definitions/invite_event.yaml" examples: diff --git a/api/server-server/joins.yaml b/api/server-server/joins.yaml index b3aebf145..11a47af67 100644 --- a/api/server-server/joins.yaml +++ b/api/server-server/joins.yaml @@ -35,13 +35,13 @@ paths: - in: path name: roomId type: string - description: The room ID that is about to be joined + description: The room ID that is about to be joined. required: true x-example: "!abc123:matrix.org" - in: path name: userId type: string - description: The user ID the join event will be for + description: The user ID the join event will be for. required: true x-example: "@someone:example.org" responses: @@ -57,29 +57,29 @@ paths: # Note: we override a bunch of parameters to change their descriptions sender: type: string - description: The user ID of the joining member + description: The user ID of the joining member. example: "@someone:example.org" origin: type: string - description: The name of the resident homeserver + description: The name of the resident homeserver. example: "matrix.org" origin_server_ts: type: integer format: int64 - description: A timestamp added by the resident homeserver + description: A timestamp added by the resident homeserver. example: 1234567890 type: type: string - description: The value ``m.room.member`` + description: The value ``m.room.member``. example: "m.room.member" state_key: type: string - description: The user ID of the joining member + description: The user ID of the joining member. example: "@someone:example.org" content: type: object title: Membership Event Content - description: The content of the event + description: The content of the event. example: {"membership": "join"} properties: membership: @@ -89,13 +89,13 @@ paths: required: ['membership'] depth: type: integer - description: This field must be present but is ignored; it may be 0 + description: This field must be present but is ignored; it may be 0. example: 12 auth_events: type: array description: |- An event reference list containing the authorization events that would - allow the member to join the room + allow the member to join the room. items: type: array maxItems: 2 @@ -112,12 +112,12 @@ paths: properties: sha256: type: string - description: The event hash + description: The event hash. example: abase64encodedsha256hashshouldbe43byteslong required: ['sha256'] redacts: type: string - description: Not used + description: Not used. required: # Every other field is already flagged as required by the $ref - state_key @@ -141,13 +141,13 @@ paths: - in: path name: roomId type: string - description: The room ID that is about to be joined + description: The room ID that is about to be joined. required: true x-example: "!abc123:matrix.org" - in: path name: eventId type: string - description: The event ID for the join event + description: The event ID for the join event. required: true x-example: "$abc123:example.org" - in: body @@ -162,45 +162,45 @@ paths: # Note: we override a bunch of parameters to change their descriptions sender: type: string - description: The user ID of the joining member + description: The user ID of the joining member. example: "@someone:example.org" origin: type: string - description: The name of the joining homeserver + description: The name of the joining homeserver. example: "matrix.org" origin_server_ts: type: integer format: int64 - description: A timestamp added by the joining homeserver + description: A timestamp added by the joining homeserver. example: 1234567890 type: type: string - description: The value ``m.room.member`` + description: The value ``m.room.member``. example: "m.room.member" state_key: type: string - description: The user ID of the joining member + description: The user ID of the joining member. example: "@someone:example.org" content: type: object title: Membership Event Content - description: The content of the event + description: The content of the event. example: {"membership": "join"} properties: membership: type: string - description: The value ``join`` + description: The value ``join``. example: "join" required: ['membership'] depth: type: integer - description: This field must be present but is ignored; it may be 0 + description: This field must be present but is ignored; it may be 0. example: 12 auth_events: type: array description: |- An event reference list containing the authorization events that would - allow the member to join the room + allow the member to join the room. items: type: array maxItems: 2 @@ -217,12 +217,12 @@ paths: properties: sha256: type: string - description: The event hash + description: The event hash. example: abase64encodedsha256hashshouldbe43byteslong required: ['sha256'] redacts: type: string - description: Not used + description: Not used. required: # Every other field is already flagged as required by the $ref - state_key @@ -237,29 +237,29 @@ paths: responses: 200: description: |- - The full state for the room, having accepted the join event + The full state for the room, having accepted the join event. schema: type: array minItems: 2 maxItems: 2 items: - type: integer - description: The value ``200`` + description: The value ``200``. example: 200 - type: object title: Room State - description: The state for the room + description: The state for the room. properties: auth_chain: type: array - description: The auth chain + description: The auth chain. items: type: object properties: {} # TODO: Verify schema state: type: array - description: The room state + description: The room state. items: type: object properties: {}