From c441e74b273d592ba5c42c101858dfea7c2096e7 Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Wed, 29 Apr 2020 20:11:23 +0200
Subject: [PATCH 01/14] README.rst: fix the contributor's surname

---
 README.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.rst b/README.rst
index 01ea8e72..61c27f15 100644
--- a/README.rst
+++ b/README.rst
@@ -46,7 +46,7 @@ To use the scripts, it is best to create a Python 3.4+ virtualenv as follows::
   virtualenv -p python3 env
   env/bin/pip install -r scripts/requirements.txt
 
-(Benjamin Synders has contributed a script for `Nix`_ users, which can be
+(Benjamin Saunders has contributed a script for `Nix`_ users, which can be
 invoked with ``nix-shell scripts/contrib/shell.nix``.)
 
 .. TODO: Possibly we need some libs installed; should record what they are.

From 202bf8abb109b628a52eb4a7f3b52dcc81a05c39 Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Wed, 29 Apr 2020 20:12:51 +0200
Subject: [PATCH 02/14] Cleanup summaries and descriptions

---
 api/client-server/content-repo.yaml | 21 +++++++++++----------
 api/client-server/joining.yaml      | 17 ++++++++++-------
 2 files changed, 21 insertions(+), 17 deletions(-)

diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml
index d596dbda..5fd1f12d 100644
--- a/api/client-server/content-repo.yaml
+++ b/api/client-server/content-repo.yaml
@@ -163,9 +163,10 @@ paths:
         - Media
   "/download/{serverName}/{mediaId}/{fileName}":
     get:
-      summary: |-
-        Download content from the content repository. This is the same as
-        the download endpoint above, except permitting a desired file name.
+      summary: Download content from the content repository overriding the file name
+      description: |-
+        This is the same as the download endpoint above, except permitting
+        a desired file name.
       operationId: getContentOverrideName
       produces: ["*/*"]
       parameters:
@@ -233,9 +234,9 @@ paths:
         - Media
   "/thumbnail/{serverName}/{mediaId}":
     get:
-      summary: |-
-        Download a thumbnail of content from the content repository. See the `thumbnailing <#thumbnails>`_
-        section for more information.
+      summary: Download a thumbnail of content from the content repository
+      description: |-
+        See the `thumbnailing <#thumbnails>`_ section for more information.
       operationId: getContentThumbnail
       produces: ["image/jpeg", "image/png"]
       parameters:
@@ -283,10 +284,10 @@ paths:
           x-example: false
           required: false
           default: true
-          description: |
-            Indicates to the server that it should not attempt to fetch the media if it is deemed
-            remote. This is to prevent routing loops where the server contacts itself. Defaults to
-            true if not provided.
+          description: |-
+            Indicates to the server that it should not attempt to fetch
+            the media if it is deemed remote. This is to prevent routing loops
+            where the server contacts itself. Defaults to true if not provided.
       responses:
         200:
           description: "A thumbnail of the requested content."
diff --git a/api/client-server/joining.yaml b/api/client-server/joining.yaml
index af38d6f9..4da86022 100644
--- a/api/client-server/joining.yaml
+++ b/api/client-server/joining.yaml
@@ -31,7 +31,8 @@ paths:
     post:
       summary: Start the requesting user participating in a particular room.
       description: |-
-        *Note that this API requires a room ID, not alias.* ``/join/{roomIdOrAlias}`` *exists if you have a room alias.*
+        *Note that this API requires a room ID, not alias.*
+        ``/join/{roomIdOrAlias}`` *exists if you have a room alias.*
 
         This API starts a user participating in a particular room, if that user
         is allowed to participate in that room. After this call, the client is
@@ -40,10 +41,6 @@ paths:
 
         After a user has joined a room, the room will appear as an entry in the
         response of the |/initialSync|_ and |/sync|_ APIs.
-
-        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.
       operationId: joinRoomById
       security:
         - accessToken: []
@@ -56,6 +53,10 @@ paths:
           x-example: "!d41d8cd:matrix.org"
         - in: body
           name: third_party_signed
+          description: |-
+            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.
           schema:
             type: object
             properties:
@@ -79,7 +80,8 @@ paths:
             required: ["room_id"]
         403:
           description: |-
-            You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
+            You do not have permission to join the room. A meaningful ``errcode``
+            and description error text will be returned. Example reasons for rejection are:
 
             - The room is invite-only and the user was not invited.
             - The user has been banned from the room.
@@ -155,7 +157,8 @@ paths:
             required: ["room_id"]
         403:
           description: |-
-            You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
+            You do not have permission to join the room. A meaningful ``errcode``
+            and description error text will be returned. Example reasons for rejection are:
 
             - The room is invite-only and the user was not invited.
             - The user has been banned from the room.

From 77783b8fc3dc6edb9c6048f359a19e781b2c8c50 Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Wed, 29 Apr 2020 20:14:12 +0200
Subject: [PATCH 03/14] Remove extraneous quotes, fix a typo

filter.yaml: quotes under |- were taken literally.
notifications.yaml: it's a number in the example, not a string
---
 api/client-server/filter.yaml        | 2 +-
 api/client-server/notifications.yaml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/api/client-server/filter.yaml b/api/client-server/filter.yaml
index db215196..bf9396e2 100644
--- a/api/client-server/filter.yaml
+++ b/api/client-server/filter.yaml
@@ -119,7 +119,7 @@ paths:
       responses:
         200:
           description: |-
-            "The filter defintion"
+            The filter definition.
           examples:
             application/json: {
                 "room": {
diff --git a/api/client-server/notifications.yaml b/api/client-server/notifications.yaml
index 87341d41..8679cb91 100644
--- a/api/client-server/notifications.yaml
+++ b/api/client-server/notifications.yaml
@@ -49,7 +49,7 @@ paths:
           name: limit
           description: Limit on the number of events to return in this request.
           required: false
-          x-example: "20"
+          x-example: 20
         - in: query
           name: only
           type: string

From ff59fc1905259bb7853d88bd2736889797906a3c Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Fri, 8 May 2020 07:40:54 +0200
Subject: [PATCH 04/14] /keys/query: Add a title in the response

The device keys structure in queryKeys is not the same as the one
defined in device_keys.yaml (it adds things on top of it).

Signed-off-by: Alexey Rusakov <Alexey.Rusakov@pm.me>
---
 api/client-server/keys.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/api/client-server/keys.yaml b/api/client-server/keys.yaml
index 69e39def..8c4a65f7 100644
--- a/api/client-server/keys.yaml
+++ b/api/client-server/keys.yaml
@@ -196,6 +196,7 @@ paths:
                 additionalProperties:
                   type: object
                   additionalProperties:
+                    title: DeviceInformation
                     allOf:
                       - $ref: definitions/device_keys.yaml
                     properties:

From c72d30513e961c9bcd94b80bd99b8a343f2b8ecf Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Mon, 25 May 2020 19:08:17 +0200
Subject: [PATCH 05/14] c2s: Add required: true to request bodies

---
 api/client-server/administrative_contact.yaml | 5 +++++
 api/client-server/create_room.yaml            | 1 +
 api/client-server/device_management.yaml      | 2 ++
 api/client-server/joining.yaml                | 2 ++
 api/client-server/keys.yaml                   | 3 +++
 api/client-server/login.yaml                  | 1 +
 api/client-server/redaction.yaml              | 1 +
 api/client-server/registration.yaml           | 3 +++
 api/client-server/search.yaml                 | 1 +
 9 files changed, 19 insertions(+)

diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml
index fc231b60..cebfb274 100644
--- a/api/client-server/administrative_contact.yaml
+++ b/api/client-server/administrative_contact.yaml
@@ -108,6 +108,7 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
@@ -195,6 +196,7 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
@@ -247,6 +249,7 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
@@ -299,6 +302,7 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
@@ -363,6 +367,7 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml
index 2487707e..2be8532d 100644
--- a/api/client-server/create_room.yaml
+++ b/api/client-server/create_room.yaml
@@ -74,6 +74,7 @@ paths:
         - in: body
           name: body
           description: The desired room configuration.
+          required: true
           schema:
             type: object
             example: {
diff --git a/api/client-server/device_management.yaml b/api/client-server/device_management.yaml
index 75ee9e44..8039d71f 100644
--- a/api/client-server/device_management.yaml
+++ b/api/client-server/device_management.yaml
@@ -152,6 +152,7 @@ paths:
           x-example: "QBUAZIFURK"
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
@@ -190,6 +191,7 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
diff --git a/api/client-server/joining.yaml b/api/client-server/joining.yaml
index 4da86022..c5781806 100644
--- a/api/client-server/joining.yaml
+++ b/api/client-server/joining.yaml
@@ -53,6 +53,7 @@ paths:
           x-example: "!d41d8cd:matrix.org"
         - in: body
           name: third_party_signed
+          required: true
           description: |-
             If supplied, the homeserver must verify that it matches a pending
             ``m.room.third_party_invite`` event in the room, and perform
@@ -134,6 +135,7 @@ paths:
           x-example: ["matrix.org", "elsewhere.ca"]
         - in: body
           name: third_party_signed
+          required: true
           schema:
             type: object
             properties:
diff --git a/api/client-server/keys.yaml b/api/client-server/keys.yaml
index 8c4a65f7..429d47ef 100644
--- a/api/client-server/keys.yaml
+++ b/api/client-server/keys.yaml
@@ -41,6 +41,7 @@ paths:
           name: keys
           description: |-
             The keys to be published
+          required: true
           schema:
             type: object
             properties:
@@ -133,6 +134,7 @@ paths:
           name: query
           description: |-
             Query defining the keys to be downloaded
+          required: true
           schema:
             type: object
             properties:
@@ -250,6 +252,7 @@ paths:
           name: query
           description: |-
             Query defining the keys to be claimed
+          required: true
           schema:
             type: object
             properties:
diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml
index f6c92638..fac9361c 100644
--- a/api/client-server/login.yaml
+++ b/api/client-server/login.yaml
@@ -82,6 +82,7 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             example: {
diff --git a/api/client-server/redaction.yaml b/api/client-server/redaction.yaml
index 907b1d16..811773d6 100644
--- a/api/client-server/redaction.yaml
+++ b/api/client-server/redaction.yaml
@@ -65,6 +65,7 @@ paths:
           x-example: "37"
         - in: body
           name: body
+          required: true
           schema:
             type: object
             example: {
diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml
index 8114299e..f57bd88c 100644
--- a/api/client-server/registration.yaml
+++ b/api/client-server/registration.yaml
@@ -84,6 +84,7 @@ paths:
           description: The kind of account to register. Defaults to ``user``.
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
@@ -336,6 +337,7 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
@@ -507,6 +509,7 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml
index 4fe72d5b..2d30ebef 100644
--- a/api/client-server/search.yaml
+++ b/api/client-server/search.yaml
@@ -45,6 +45,7 @@ paths:
           x-example: "YWxsCgpOb25lLDM1ODcwOA"
         - in: body
           name: body
+          required: true
           schema:
             type: object
             example: {

From 6cfb94562e1fcc99c2837d1ef2a1f5eac904b82e Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Mon, 25 May 2020 20:40:00 +0200
Subject: [PATCH 06/14] c2s: clean up $ref objects

* Most of the changes: align to the $ref object definition
  (https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03#section-3)
  that says that any attribute other than $ref be ignored.
* Remove extraneous leading ./ in $ref paths
* Fix an apparent typo in registration.yaml:
  /account/password/msisdn/requestToken used a file from ../identity/*
  instead of its c2s namesake.
---
 api/client-server/administrative_contact.yaml | 13 ++++----
 api/client-server/device_management.yaml      | 12 ++++---
 api/client-server/login.yaml                  | 16 ++++-----
 api/client-server/registration.yaml           | 33 ++++++++++---------
 api/client-server/search.yaml                 |  3 +-
 api/client-server/wellknown.yaml              |  1 -
 6 files changed, 42 insertions(+), 36 deletions(-)

diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml
index cebfb274..72565b68 100644
--- a/api/client-server/administrative_contact.yaml
+++ b/api/client-server/administrative_contact.yaml
@@ -201,10 +201,11 @@ paths:
             type: object
             properties:
               auth:
-                description: |-
-                    Additional authentication information for the
-                    user-interactive authentication API.
-                $ref: "definitions/auth_data.yaml"
+                allOf:
+                - description: |-
+                      Additional authentication information for the
+                      user-interactive authentication API.
+                - $ref: "definitions/auth_data.yaml"
               client_secret:
                 type: string
                 description: The client secret used in the session with the homeserver.
@@ -432,7 +433,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "./definitions/request_email_validation.yaml"
+            $ref: "definitions/request_email_validation.yaml"
       responses:
         200:
           description: |-
@@ -482,7 +483,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "./definitions/request_msisdn_validation.yaml"
+            $ref: "definitions/request_msisdn_validation.yaml"
       responses:
         200:
           description: An SMS message was sent to the given phone number.
diff --git a/api/client-server/device_management.yaml b/api/client-server/device_management.yaml
index 8039d71f..094084bf 100644
--- a/api/client-server/device_management.yaml
+++ b/api/client-server/device_management.yaml
@@ -83,7 +83,7 @@ paths:
           schema:
             type: object
             allOf:
-               - $ref: "definitions/client_device.yaml"
+              - $ref: "definitions/client_device.yaml"
           examples:
             application/json: {
                 "device_id": "QBUAZIFURK",
@@ -158,9 +158,10 @@ paths:
             properties:
               auth:
                 description: |-
-                    Additional authentication information for the
-                    user-interactive authentication API.
-                "$ref": "definitions/auth_data.yaml"
+                  Additional authentication information for the
+                  user-interactive authentication API.
+                allOf:
+                  - "$ref": "definitions/auth_data.yaml"
       responses:
         200:
           description: |-
@@ -203,10 +204,11 @@ paths:
                   description: A list of device IDs.
                 example: ["QBUAZIFURK", "AUIECTSRND"]
               auth:
+                allOf:
+                  - "$ref": "definitions/auth_data.yaml"
                 description: |-
                     Additional authentication information for the
                     user-interactive authentication API.
-                "$ref": "definitions/auth_data.yaml"
             required:
               - devices
       responses:
diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml
index fac9361c..d37d135d 100644
--- a/api/client-server/login.yaml
+++ b/api/client-server/login.yaml
@@ -100,7 +100,6 @@ paths:
                 enum: ["m.login.password", "m.login.token"]
                 description: The login type being used.
               identifier:
-                description: Identification information for the user.
                 "$ref": "definitions/user_identifier.yaml"
               user:
                 type: string
@@ -176,13 +175,14 @@ paths:
                   ID of the logged-in device. Will be the same as the
                   corresponding parameter in the request, if one was specified.
               well_known:
-                type: object
-                description: |-
-                  Optional client configuration provided by the server. If present,
-                  clients SHOULD use the provided object to reconfigure themselves,
-                  optionally validating the URLs within. This object takes the same
-                  form as the one returned from .well-known autodiscovery.
-                "$ref": "definitions/wellknown/full.yaml"
+                allOf:
+                  - type: object
+                    description: |-
+                      Optional client configuration provided by the server. If present,
+                      clients SHOULD use the provided object to reconfigure themselves,
+                      optionally validating the URLs within. This object takes the same
+                      form as the one returned from .well-known autodiscovery.
+                  - "$ref": "definitions/wellknown/full.yaml"
         400:
           description: |-
             Part of the request was invalid. For example, the login type may not be recognised.
diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml
index f57bd88c..cf1a2f23 100644
--- a/api/client-server/registration.yaml
+++ b/api/client-server/registration.yaml
@@ -89,13 +89,14 @@ paths:
             type: object
             properties:
               auth:
-                description: |-
-                  Additional authentication information for the
-                  user-interactive authentication API. Note that this
-                  information is *not* used to define how the registered user
-                  should be authenticated, but is instead used to
-                  authenticate the ``register`` call itself.
-                "$ref": "definitions/auth_data.yaml"
+                allOf:
+                - description: |-
+                    Additional authentication information for the
+                    user-interactive authentication API. Note that this
+                    information is *not* used to define how the registered user
+                    should be authenticated, but is instead used to
+                    authenticate the ``register`` call itself.
+                - "$ref": "definitions/auth_data.yaml"
               username:
                 type: string
                 description: |-
@@ -228,7 +229,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "./definitions/request_email_validation.yaml"
+            $ref: "definitions/request_email_validation.yaml"
       responses:
         200:
           description: |-
@@ -278,7 +279,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "./definitions/request_msisdn_validation.yaml"
+            $ref: "definitions/request_msisdn_validation.yaml"
       responses:
         200:
           description: |-
@@ -346,9 +347,10 @@ paths:
                 description: The new password for the account.
                 example: "ihatebananas"
               auth:
-                description: |-
-                  Additional authentication information for the user-interactive authentication API.
-                "$ref": "definitions/auth_data.yaml"
+                allOf:
+                - description: |-
+                    Additional authentication information for the user-interactive authentication API.
+                - "$ref": "definitions/auth_data.yaml"
             required: ["new_password"]
       responses:
         200:
@@ -397,7 +399,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "./definitions/request_email_validation.yaml"
+            $ref: "definitions/request_email_validation.yaml"
       responses:
         200:
           description: An email was sent to the given address.
@@ -455,7 +457,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "../identity/definitions/request_msisdn_validation.yaml"
+            $ref: "definitions/request_msisdn_validation.yaml"
       responses:
         200:
           description: An SMS message was sent to the given phone number.
@@ -516,7 +518,8 @@ paths:
               auth:
                 description: |-
                   Additional authentication information for the user-interactive authentication API.
-                "$ref": "definitions/auth_data.yaml"
+                allOf:
+                  - $ref: "definitions/auth_data.yaml"
               id_server:
                 type: string
                 description: |-
diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml
index 2d30ebef..27e06727 100644
--- a/api/client-server/search.yaml
+++ b/api/client-server/search.yaml
@@ -96,7 +96,8 @@ paths:
                         # for now :/
                         description: |-
                           This takes a `filter`_.
-                        $ref: "definitions/room_event_filter.yaml"
+                        allOf:
+                          - $ref: "definitions/room_event_filter.yaml"
                       order_by:
                         title: "Ordering"
                         type: string
diff --git a/api/client-server/wellknown.yaml b/api/client-server/wellknown.yaml
index b63bd041..3d1c0ae0 100644
--- a/api/client-server/wellknown.yaml
+++ b/api/client-server/wellknown.yaml
@@ -39,7 +39,6 @@ paths:
         200:
           description: Server discovery information.
           schema:
-            type: object
             "$ref": "definitions/wellknown/full.yaml"
         404:
           description: No server discovery information available.

From 67a8176903e8361310c32a7b0559f3adc504012d Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Thu, 28 May 2020 13:54:36 +0200
Subject: [PATCH 07/14] Clarify officially that we use multiple API files

This is not something endorsed by the OpenAPI spec, just our practice.
---
 api/openapi_extensions.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/api/openapi_extensions.md b/api/openapi_extensions.md
index 339452ba..c614793d 100644
--- a/api/openapi_extensions.md
+++ b/api/openapi_extensions.md
@@ -6,6 +6,19 @@ across the specification. The defined extensions are listed below. Extensions
 should not break parsers, however if extra functionality is required, aware
 parsers should be able to take advantage of the added syntax.
 
+## Using multiple files to describe API
+
+To ease API design and management, the API definition is split across several
+files. Each of these files is self-contained valid OpenAPI (except
+client-server files that become valid OpenAPI after substituting
+`%CLIENT_MAJOR_VERSION%` with `unstable` or an API release).
+
+There is no single root file in the source tree as OpenAPI requires; this file
+can be generated by `dump_swagger.py` (also doing the substitution mentioned
+above). The script does not convert the extensions described further in this
+document (`oneOf` and parameter exploding) so there can be minor
+interoperability issues with tooling that expects compliant Swagger. 
+
 ## Extensible Query Parameters
 
 <!-- TODO: Remove and change instances to 'explode' after OpenAPI/Swagger v3 update -->

From b789f3e10b4f4b5e162c705af222bb740f881b5b Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Thu, 28 May 2020 13:56:29 +0200
Subject: [PATCH 08/14] dump-swagger.py: fix a typo in the help string

---
 scripts/dump-swagger.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/dump-swagger.py b/scripts/dump-swagger.py
index 0b9f8486..232ca8ad 100755
--- a/scripts/dump-swagger.py
+++ b/scripts/dump-swagger.py
@@ -43,7 +43,7 @@ parser = argparse.ArgumentParser(
 parser.add_argument(
     "--client_release", "-c", metavar="LABEL",
     default="unstable",
-    help="""The client-server release version to gneerate for. Default:
+    help="""The client-server release version to generate for. Default:
     %(default)s""",
 )
 parser.add_argument(

From 040a91f42d724b157e49407d19f5f30e21a01865 Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Thu, 28 May 2020 14:11:47 +0200
Subject: [PATCH 09/14] api/: More cleanup in descriptions

(and a fix in one example).
---
 api/application-service/transactions.yaml | 3 +--
 api/client-server/device_management.yaml  | 6 +++---
 api/client-server/kicking.yaml            | 3 ++-
 api/client-server/presence.yaml           | 2 +-
 api/client-server/profile.yaml            | 4 ++--
 api/client-server/room_upgrades.yaml      | 1 -
 api/server-server/public_rooms.yaml       | 2 +-
 7 files changed, 10 insertions(+), 11 deletions(-)

diff --git a/api/application-service/transactions.yaml b/api/application-service/transactions.yaml
index 09f15276..a557325c 100644
--- a/api/application-service/transactions.yaml
+++ b/api/application-service/transactions.yaml
@@ -50,7 +50,7 @@ paths:
           x-example: "35"
         - in: body
           name: body
-          description: A list of events.
+          description: Transaction information
           schema:
             type: object
             example: {
@@ -59,7 +59,6 @@ paths:
                 {"$ref": "../../event-schemas/examples/m.room.message$m.text"}
               ]
             }
-            description: Transaction information
             properties:
               events:
                 type: array
diff --git a/api/client-server/device_management.yaml b/api/client-server/device_management.yaml
index 094084bf..c42ebbd7 100644
--- a/api/client-server/device_management.yaml
+++ b/api/client-server/device_management.yaml
@@ -119,9 +119,9 @@ paths:
               display_name:
                 type: string
                 description: |-
-                    The new display name for this device. If not given, the
-                    display name is unchanged.
-                example: My other phone
+                  The new display name for this device. If not given, the
+                  display name is unchanged.
+            example: { "display_name": "My other phone" }
       responses:
         200:
           description: The device was successfully updated.
diff --git a/api/client-server/kicking.yaml b/api/client-server/kicking.yaml
index 7fbee38b..fd3f1698 100644
--- a/api/client-server/kicking.yaml
+++ b/api/client-server/kicking.yaml
@@ -77,7 +77,8 @@ paths:
             type: object
         403:
           description: |-
-            You do not have permission to kick the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
+            You do not have permission to kick the user from the room. A meaningful ``errcode`` and
+            description error text will be returned. Example reasons for rejections are:
 
             - The kicker is not currently in the room.
             - The kickee is not currently in the room.
diff --git a/api/client-server/presence.yaml b/api/client-server/presence.yaml
index 874ac59b..b3a8bb02 100644
--- a/api/client-server/presence.yaml
+++ b/api/client-server/presence.yaml
@@ -62,7 +62,7 @@ paths:
                 description: The new presence state.
               status_msg:
                 type: string
-                description: "The status message to attach to this state."
+                description: The status message to attach to this state.
             required: ["presence"]
       responses:
         200:
diff --git a/api/client-server/profile.yaml b/api/client-server/profile.yaml
index c8dc4056..db998e6c 100644
--- a/api/client-server/profile.yaml
+++ b/api/client-server/profile.yaml
@@ -45,7 +45,7 @@ paths:
           x-example: "@alice:example.com"
         - in: body
           name: displayName
-          description: The display name info.
+          description: The new display name information.
           required: true
           schema:
             type: object
@@ -119,7 +119,7 @@ paths:
           x-example: "@alice:example.com"
         - in: body
           name: avatar_url
-          description: The avatar url info.
+          description: The new avatar information.
           required: true
           schema:
             type: object
diff --git a/api/client-server/room_upgrades.yaml b/api/client-server/room_upgrades.yaml
index 3aaaadcb..97ef611e 100644
--- a/api/client-server/room_upgrades.yaml
+++ b/api/client-server/room_upgrades.yaml
@@ -45,7 +45,6 @@ paths:
         - in: body
           name: body
           required: true
-          description: The request body
           schema:
             type: object
             properties:
diff --git a/api/server-server/public_rooms.yaml b/api/server-server/public_rooms.yaml
index 0216f0c3..5324eac3 100644
--- a/api/server-server/public_rooms.yaml
+++ b/api/server-server/public_rooms.yaml
@@ -86,7 +86,7 @@ paths:
           name: body
           required: true
           description: |-
-            Options for which rooms to return.
+            Options for which rooms to return, or empty object to use defaults.
           schema:
             type: object
             properties:

From 48af2e5b47c2dcf6d4ffdcfd9e90e66de7e64990 Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Thu, 28 May 2020 14:17:01 +0200
Subject: [PATCH 10/14] joining.yaml: put descriptions next to their properties

Fixing the problem described in https://github.com/matrix-org/matrix-doc/pull/2518#issuecomment-621684187
---
 api/client-server/joining.yaml | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/api/client-server/joining.yaml b/api/client-server/joining.yaml
index c5781806..5f14f528 100644
--- a/api/client-server/joining.yaml
+++ b/api/client-server/joining.yaml
@@ -54,15 +54,16 @@ paths:
         - in: body
           name: third_party_signed
           required: true
-          description: |-
-            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.
           schema:
             type: object
             properties:
               third_party_signed:
-                $ref: "definitions/third_party_signed.yaml"
+                allOf:
+                - $ref: "definitions/third_party_signed.yaml"
+                description: |-
+                  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.
       responses:
         200:
           description: |-
@@ -110,10 +111,6 @@ paths:
 
         After a user has joined a room, the room will appear as an entry in the
         response of the |/initialSync|_ and |/sync|_ APIs.
-
-        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.
       operationId: joinRoom
       security:
         - accessToken: []
@@ -140,7 +137,12 @@ paths:
             type: object
             properties:
               third_party_signed:
-                $ref: "definitions/third_party_signed.yaml"
+                allOf:
+                  - $ref: "definitions/third_party_signed.yaml"
+                description: |-
+                  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.
       responses:
         200:
           description: |-

From 3b5340539dd25c2190593f7bceea37b351111824 Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Thu, 28 May 2020 14:40:29 +0200
Subject: [PATCH 11/14] c2s: Make allOf and description siblings throughout the
 PR

The overall mess with allOf will be addressed separately; this PR just
puts $ref under allOf to fix the glaring misuse of $ref objects.
---
 api/client-server/administrative_contact.yaml |  6 +++---
 api/client-server/login.yaml                  | 11 +++++------
 api/client-server/registration.yaml           |  8 ++++----
 3 files changed, 12 insertions(+), 13 deletions(-)

diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml
index 72565b68..f8cdf5a0 100644
--- a/api/client-server/administrative_contact.yaml
+++ b/api/client-server/administrative_contact.yaml
@@ -201,10 +201,10 @@ paths:
             type: object
             properties:
               auth:
+                description: |-
+                  Additional authentication information for the
+                  user-interactive authentication API.
                 allOf:
-                - description: |-
-                      Additional authentication information for the
-                      user-interactive authentication API.
                 - $ref: "definitions/auth_data.yaml"
               client_secret:
                 type: string
diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml
index d37d135d..a959b312 100644
--- a/api/client-server/login.yaml
+++ b/api/client-server/login.yaml
@@ -175,13 +175,12 @@ paths:
                   ID of the logged-in device. Will be the same as the
                   corresponding parameter in the request, if one was specified.
               well_known:
+                description: |-
+                  Optional client configuration provided by the server. If present,
+                  clients SHOULD use the provided object to reconfigure themselves,
+                  optionally validating the URLs within. This object takes the same
+                  form as the one returned from .well-known autodiscovery.
                 allOf:
-                  - type: object
-                    description: |-
-                      Optional client configuration provided by the server. If present,
-                      clients SHOULD use the provided object to reconfigure themselves,
-                      optionally validating the URLs within. This object takes the same
-                      form as the one returned from .well-known autodiscovery.
                   - "$ref": "definitions/wellknown/full.yaml"
         400:
           description: |-
diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml
index cf1a2f23..c535bb99 100644
--- a/api/client-server/registration.yaml
+++ b/api/client-server/registration.yaml
@@ -89,13 +89,13 @@ paths:
             type: object
             properties:
               auth:
-                allOf:
-                - description: |-
+                description: |-
                     Additional authentication information for the
                     user-interactive authentication API. Note that this
                     information is *not* used to define how the registered user
                     should be authenticated, but is instead used to
                     authenticate the ``register`` call itself.
+                allOf:
                 - "$ref": "definitions/auth_data.yaml"
               username:
                 type: string
@@ -347,9 +347,9 @@ paths:
                 description: The new password for the account.
                 example: "ihatebananas"
               auth:
-                allOf:
-                - description: |-
+                description: |-
                     Additional authentication information for the user-interactive authentication API.
+                allOf:
                 - "$ref": "definitions/auth_data.yaml"
             required: ["new_password"]
       responses:

From d3b41941aa2228f675f5100428c7390d10ba63ce Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Wed, 10 Jun 2020 21:16:54 +0200
Subject: [PATCH 12/14] key_backup.yaml: make body parameters required

Along the same lines as c72d3051.
---
 api/client-server/key_backup.yaml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/api/client-server/key_backup.yaml b/api/client-server/key_backup.yaml
index 34dce118..603d1c8c 100644
--- a/api/client-server/key_backup.yaml
+++ b/api/client-server/key_backup.yaml
@@ -39,6 +39,7 @@ paths:
         - in: body
           name: version
           description: "The backup configuration."
+          required: true
           schema:
             type: object
             properties:
@@ -257,6 +258,7 @@ paths:
         - in: body
           name: version
           description: "The backup configuration"
+          required: true
           schema:
             type: object
             properties:
@@ -398,6 +400,7 @@ paths:
         - in: body
           name: data
           description: "The key data."
+          required: true
           schema:
             "$ref": "definitions/key_backup_data.yaml"
       responses:
@@ -568,6 +571,7 @@ paths:
         - in: body
           description: "The backup data"
           name: backupData
+          required: true
           schema:
             type: object
             properties:
@@ -763,6 +767,7 @@ paths:
         - in: body
           description: "The backup data"
           name: backupData
+          required: true
           schema:
             type: object
             properties:

From 57f0c8346facacded144996726b0f4fc0ee7d539 Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Wed, 10 Jun 2020 18:14:24 +0200
Subject: [PATCH 13/14] message_pagination.yaml: more $ref cleanup

---
 api/client-server/message_pagination.yaml | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml
index 22828219..425240e3 100644
--- a/api/client-server/message_pagination.yaml
+++ b/api/client-server/message_pagination.yaml
@@ -111,8 +111,6 @@ paths:
                   for ``dir=f`` in chronological order, so that events start
                   at the ``from`` point.
                 items:
-                  type: object
-                  title: RoomEvent
                   "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
               state:
                 type: array
@@ -126,8 +124,6 @@ paths:
                   sent to the client in prior calls to this endpoint, assuming
                   the membership of those members has not changed.
                 items:
-                  type: object
-                  title: RoomStateEvent
                   $ref: "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
           examples:
             application/json: {

From c76d53c11a953bb84ac3aac467d2544e561e9ff9 Mon Sep 17 00:00:00 2001
From: Kitsune Ral <Kitsune-Ral@users.sf.net>
Date: Thu, 18 Jun 2020 11:03:43 +0200
Subject: [PATCH 14/14] Apply suggestions from code review

---
 api/client-server/content-repo.yaml | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml
index 5fd1f12d..71c35f01 100644
--- a/api/client-server/content-repo.yaml
+++ b/api/client-server/content-repo.yaml
@@ -165,8 +165,9 @@ paths:
     get:
       summary: Download content from the content repository overriding the file name
       description: |-
-        This is the same as the download endpoint above, except permitting
-        a desired file name.
+        This will download content from the content repository (same as
+        the previous endpoint) but replace the target file name with the one
+        provided by the caller.
       operationId: getContentOverrideName
       produces: ["*/*"]
       parameters:
@@ -236,6 +237,7 @@ paths:
     get:
       summary: Download a thumbnail of content from the content repository
       description: |-
+        Download a thumbnail of content from the content repository.
         See the `thumbnailing <#thumbnails>`_ section for more information.
       operationId: getContentThumbnail
       produces: ["image/jpeg", "image/png"]