Merge pull request #2795 from matrix-org/travis/spec/msc2367-reason

Add membership reasons to the spec for all membership events

api/client-server/banning.yaml

@@ -61,7 +61,7 @@ paths:
                 description: The fully qualified user ID of the user being banned.
               reason:
                 type: string
-                description: The reason the user has been banned. This will be supplied as the 
+                description: The reason the user has been banned. This will be supplied as the
                   ``reason`` on the target's updated `m.room.member`_ event.
             required: ["user_id"]
       responses:
@@ -111,12 +111,18 @@ paths:
           schema:
             type: object
             example: {
-                "user_id": "@cheeky_monkey:matrix.org"
-              }
+              "user_id": "@cheeky_monkey:matrix.org",
+              "reason": "They've been banned long enough"
+            }
             properties:
               user_id:
                 type: string
                 description: The fully qualified user ID of the user being unbanned.
+              reason:
+                type: string
+                description: |-
+                  Optional reason to be included as the ``reason`` on the subsequent
+                  membership event.
             required: ["user_id"]
       responses:
         200:

api/client-server/inviting.yaml

@@ -67,12 +67,18 @@ paths:
           schema:
             type: object
             example: {
-                "user_id": "@cheeky_monkey:matrix.org"
-              }
+              "user_id": "@cheeky_monkey:matrix.org",
+              "reason": "Welcome to the team!"
+            }
             properties:
               user_id:
                 type: string
                 description: The fully qualified user ID of the invitee.
+              reason:
+                type: string
+                description: |-
+                  Optional reason to be included as the ``reason`` on the subsequent
+                  membership event.
             required: ["user_id"]
       responses:
         200:

api/client-server/joining.yaml

@@ -52,7 +52,7 @@ paths:
           required: true
           x-example: "!d41d8cd:matrix.org"
         - in: body
-          name: third_party_signed
+          name: body
           required: true
           schema:
             type: object
@@ -64,6 +64,12 @@ paths:
                   If supplied, the homeserver must verify that it matches a pending
                   ``m.room.third_party_invite`` event in the room, and perform
                   key validity checking if required by the event.
+              reason:
+                type: string
+                description: |-
+                  Optional reason to be included as the ``reason`` on the subsequent
+                  membership event.
+                example: "Looking for support"
       responses:
         200:
           description: |-
@@ -131,7 +137,7 @@ paths:
             must be participating in the room.
           x-example: ["matrix.org", "elsewhere.ca"]
         - in: body
-          name: third_party_signed
+          name: body
           required: true
           schema:
             type: object
@@ -143,6 +149,12 @@ paths:
                   If a ``third_party_signed`` was supplied, the homeserver must verify
                   that it matches a pending ``m.room.third_party_invite`` event in the
                   room, and perform key validity checking if required by the event.
+              reason:
+                type: string
+                description: |-
+                  Optional reason to be included as the ``reason`` on the subsequent
+                  membership event.
+                example: "Looking for support"
       responses:
         200:
           description: |-

api/client-server/leaving.yaml

@@ -52,6 +52,20 @@ paths:
           description: The room identifier to leave.
           required: true
           x-example: "!nkl290a:matrix.org"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            example: {
+              "reason": "Saying farewell - thanks for the support!"
+            }
+            properties:
+              reason:
+                type: string
+                description: |-
+                  Optional reason to be included as the ``reason`` on the subsequent
+                  membership event.
       responses:
         200:
           description: |-