Deduplicate RoomKeysUpdateResponse (#2073)

And add a link to the endpoint that is mentionned while we're at it.

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

changelogs/internal/newsfragments/2073.clarification

@@ -0,0 +1 @@
+Deduplicate the definition of `RoomKeysUpdateResponse`.

data/api/client-server/key_backup.yaml

@@ -438,22 +438,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
-                title: RoomKeysUpdateResponse
-                properties:
-                  etag:
-                    description: |-
-                      The new etag value representing stored keys in the backup.
-                      See `GET /room_keys/version/{version}` for more details.
-                    type: string
-                    example: abcdefg
-                  count:
-                    description: The number of keys stored in the backup
-                    type: integer
-                    example: 10
-                required:
-                  - etag
-                  - count
         "403":
           description: |-
             The version specified does not match the current backup version.
@@ -571,22 +556,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
-                title: RoomKeysUpdateResponse
-                properties:
-                  etag:
-                    description: |-
-                      The new etag value representing stored keys in the backup.
-                      See `GET /room_keys/version/{version}` for more details.
-                    type: string
-                    example: abcdefg
-                  count:
-                    description: The number of keys stored in the backup
-                    type: integer
-                    example: 10
-                required:
-                  - etag
-                  - count
         "404":
           description: The backup was not found.
           content:
@@ -644,22 +614,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
-                title: RoomKeysUpdateResponse
-                properties:
-                  etag:
-                    description: |-
-                      The new etag value representing stored keys in the backup.
-                      See `GET /room_keys/version/{version}` for more details.
-                    type: string
-                    example: abcdefg
-                  count:
-                    description: The number of keys stored in the backup
-                    type: integer
-                    example: 10
-                required:
-                  - etag
-                  - count
         "403":
           description: |-
             The version specified does not match the current backup version.
@@ -778,22 +733,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
-                title: RoomKeysUpdateResponse
-                properties:
-                  etag:
-                    description: |-
-                      The new etag value representing stored keys in the backup.
-                      See `GET /room_keys/version/{version}` for more details.
-                    type: string
-                    example: abcdefg
-                  count:
-                    description: The number of keys stored in the backup
-                    type: integer
-                    example: 10
-                required:
-                  - etag
-                  - count
         "404":
           description: The backup was not found.
           content:
@@ -866,22 +806,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
-                title: RoomKeysUpdateResponse
-                properties:
-                  etag:
-                    description: |-
-                      The new etag value representing stored keys in the backup.
-                      See `GET /room_keys/version/{version}` for more details.
-                    type: string
-                    example: abcdefg
-                  count:
-                    description: The number of keys stored in the backup
-                    type: integer
-                    example: 10
-                required:
-                  - etag
-                  - count
         "403":
           description: |-
             The version specified does not match the current backup version.
@@ -1007,22 +932,7 @@ paths:
           content:
             application/json:
               schema:
-                type: object
+                $ref: "#/components/schemas/RoomKeysUpdateResponse"
-                title: RoomKeysUpdateResponse
-                properties:
-                  etag:
-                    description: |-
-                      The new etag value representing stored keys in the backup.
-                      See `GET /room_keys/version/{version}` for more details.
-                    type: string
-                    example: abcdefg
-                  count:
-                    description: The number of keys stored in the backup
-                    type: integer
-                    example: 10
-                required:
-                  - etag
-                  - count
         "404":
           description: The backup was not found.
           content:
@@ -1056,6 +966,26 @@ servers:
       basePath:
         default: /_matrix/client/v3
 components:
+  schemas:
+    RoomKeysUpdateResponse:
+      type: object
+      title: RoomKeysUpdateResponse
+      properties:
+        etag:
+          description: |-
+            The new etag value representing stored keys in the backup.
+            
+            See [`GET /room_keys/version/{version}`](client-server-api/#get_matrixclientv3room_keysversionversion)
+            for more details.
+          type: string
+          example: abcdefg
+        count:
+          description: The number of keys stored in the backup
+          type: integer
+          example: 10
+      required:
+        - etag
+        - count
   securitySchemes:
     accessTokenQuery:
       $ref: definitions/security.yaml#/accessTokenQuery