Clarify what fields are required when deleting a pusher (#1321)

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/client_server/newsfragments/1321.clarification

@@ -0,0 +1 @@
+Clarify what fields are required when deleting a pusher

data/api/client-server/pusher.yaml

@@ -139,6 +139,11 @@ paths:
         This endpoint allows the creation, modification and deletion of [pushers](/client-server-api/#push-notifications)
         for this user ID. The behaviour of this endpoint varies depending on the
         values in the JSON body.
+
+        If `kind` is not `null`, the pusher with this `app_id` and `pushkey`
+        for this user is updated, or it is created if it doesn't exist. If
+        `kind` is `null`, the pusher with this `app_id` and `pushkey` for this
+        user is deleted.
       operationId: postPusher
       security:
         - accessToken: []
@@ -177,7 +182,9 @@ paths:
                   If the `kind` is `"email"`, this is the email address to
                   send notifications to.
               kind:
-                type: string
+                type:
+                  - "string"
+                  - "null"
                 description: |-
                   The kind of pusher to configure. `"http"` makes a pusher that
                   sends HTTP pokes. `"email"` makes a pusher that emails the
@@ -194,13 +201,13 @@ paths:
               app_display_name:
                 type: string
                 description: |-
-                  A string that will allow the user to identify what application
+                  Required if `kind` is not `null`. A string that will allow the
-                  owns this pusher.
+                  user to identify what application owns this pusher.
               device_display_name:
                 type: string
                 description: |-
-                  A string that will allow the user to identify what device owns
+                  Required if `kind` is not `null`. A string that will allow the
-                  this pusher.
+                  user to identify what device owns this pusher.
               profile_tag:
                 type: string
                 description: |-
@@ -209,14 +216,15 @@ paths:
               lang:
                 type: string
                 description: |-
-                  The preferred language for receiving notifications (e.g. 'en'
+                  Required if `kind` is not `null`. The preferred language for
-                  or 'en-US').
+                  receiving notifications (e.g. 'en' or 'en-US').
               data:
                 type: object
                 description: |-
-                  A dictionary of information for the pusher implementation
+                  Required if `kind` is not `null`. A dictionary of information
-                  itself. If `kind` is `http`, this should contain `url`
+                  for the pusher implementation itself. If `kind` is `http`,
-                  which is the URL to use to send notifications to.
+                  this should contain `url` which is the URL to use to send
+                  notifications to.
                 title: PusherData
                 properties:
                   url:
@@ -243,8 +251,7 @@ paths:
                   different user IDs. Otherwise, the homeserver must remove any
                   other pushers with the same App ID and pushkey for different
                   users. The default is `false`.
-            required: ['kind', 'app_id', 'app_display_name',
+            required: ['kind', 'app_id', 'pushkey']
-                'device_display_name', 'pushkey', 'lang', 'data']
       responses:
         200:
           description: The pusher was set.