diff --git a/README.rst b/README.rst
index 01ea8e725..61c27f150 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.
diff --git a/api/application-service/transactions.yaml b/api/application-service/transactions.yaml
index 09f152765..a557325c5 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/administrative_contact.yaml b/api/client-server/administrative_contact.yaml
index fc231b602..f8cdf5a0f 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,14 +196,16 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             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"
               client_secret:
                 type: string
                 description: The client secret used in the session with the homeserver.
@@ -247,6 +250,7 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
@@ -299,6 +303,7 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
@@ -363,6 +368,7 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
@@ -427,7 +433,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "./definitions/request_email_validation.yaml"
+            $ref: "definitions/request_email_validation.yaml"
       responses:
         200:
           description: |-
@@ -477,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/content-repo.yaml b/api/client-server/content-repo.yaml
index d596dbda3..71c35f016 100644
--- a/api/client-server/content-repo.yaml
+++ b/api/client-server/content-repo.yaml
@@ -163,9 +163,11 @@ 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 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:
@@ -233,9 +235,10 @@ 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: |-
+        Download a thumbnail of content from the content repository.
+        See the `thumbnailing <#thumbnails>`_ section for more information.
       operationId: getContentThumbnail
       produces: ["image/jpeg", "image/png"]
       parameters:
@@ -283,10 +286,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/create_room.yaml b/api/client-server/create_room.yaml
index 446d8aef6..8b4cf9e9d 100644
--- a/api/client-server/create_room.yaml
+++ b/api/client-server/create_room.yaml
@@ -80,6 +80,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 75ee9e444..c42ebbd7c 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",
@@ -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.
@@ -152,14 +152,16 @@ paths:
           x-example: "QBUAZIFURK"
         - in: body
           name: body
+          required: true
           schema:
             type: object
             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: |-
@@ -190,6 +192,7 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
@@ -201,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/filter.yaml b/api/client-server/filter.yaml
index db2151960..bf9396e2f 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/joining.yaml b/api/client-server/joining.yaml
index af38d6f97..5f14f5283 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,11 +53,17 @@ paths:
           x-example: "!d41d8cd:matrix.org"
         - in: body
           name: third_party_signed
+          required: true
           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: |-
@@ -79,7 +82,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.
@@ -107,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: []
@@ -132,11 +132,17 @@ paths:
           x-example: ["matrix.org", "elsewhere.ca"]
         - in: body
           name: third_party_signed
+          required: true
           schema:
             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: |-
@@ -155,7 +161,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.
diff --git a/api/client-server/key_backup.yaml b/api/client-server/key_backup.yaml
index 31c66a258..682372d79 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:
             $ref: "definitions/room_key_backup.yaml"
       responses:
@@ -734,6 +738,7 @@ paths:
         - in: body
           description: "The backup data."
           name: backupData
+          required: true
           schema:
             type: object
             properties:
diff --git a/api/client-server/keys.yaml b/api/client-server/keys.yaml
index e172ea8a4..d92dff033 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:
@@ -196,6 +198,7 @@ paths:
                 additionalProperties:
                   type: object
                   additionalProperties:
+                    title: DeviceInformation
                     allOf:
                       - $ref: definitions/device_keys.yaml
                     properties:
@@ -249,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/kicking.yaml b/api/client-server/kicking.yaml
index 7fbee38bd..fd3f16986 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/login.yaml b/api/client-server/login.yaml
index f122f209e..7844172f3 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: {
@@ -99,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
@@ -175,13 +175,13 @@ 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:
+                  - "$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/message_pagination.yaml b/api/client-server/message_pagination.yaml
index 228282198..425240e3c 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: {
diff --git a/api/client-server/notifications.yaml b/api/client-server/notifications.yaml
index 87341d418..8679cb918 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
diff --git a/api/client-server/presence.yaml b/api/client-server/presence.yaml
index 874ac59b9..b3a8bb029 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 c8dc40563..db998e6c7 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/redaction.yaml b/api/client-server/redaction.yaml
index 907b1d16a..811773d65 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 bab9139c8..69316b8f5 100644
--- a/api/client-server/registration.yaml
+++ b/api/client-server/registration.yaml
@@ -84,17 +84,19 @@ paths:
           description: The kind of account to register. Defaults to ``user``.
         - in: body
           name: body
+          required: true
           schema:
             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"
+                    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
                 description: |-
@@ -227,7 +229,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "./definitions/request_email_validation.yaml"
+            $ref: "definitions/request_email_validation.yaml"
       responses:
         200:
           description: |-
@@ -277,7 +279,7 @@ paths:
           name: body
           required: true
           schema:
-            $ref: "./definitions/request_msisdn_validation.yaml"
+            $ref: "definitions/request_msisdn_validation.yaml"
       responses:
         200:
           description: |-
@@ -336,6 +338,7 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
@@ -354,8 +357,9 @@ paths:
                 example: true
               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"
             required: ["new_password"]
       responses:
         200:
@@ -404,7 +408,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.
@@ -462,7 +466,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,13 +520,15 @@ paths:
       parameters:
         - in: body
           name: body
+          required: true
           schema:
             type: object
             properties:
               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/room_upgrades.yaml b/api/client-server/room_upgrades.yaml
index 3aaaadcb4..97ef611e5 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/client-server/search.yaml b/api/client-server/search.yaml
index 4fe72d5bf..27e06727f 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: {
@@ -95,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 b63bd0410..3d1c0ae03 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.
diff --git a/api/openapi_extensions.md b/api/openapi_extensions.md
index fced21fc7..b450e49f7 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 -->
diff --git a/api/server-server/public_rooms.yaml b/api/server-server/public_rooms.yaml
index 0216f0c31..5324eac39 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:
diff --git a/scripts/dump-swagger.py b/scripts/dump-swagger.py
index 0b9f8486e..232ca8adc 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(