Merge pull request #2518 from matrix-org/kitsune/cleanup

Assorted cleanup pieces

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.

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

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
+                  Additional authentication information for the
-                    user-interactive authentication API.
+                  user-interactive authentication API.
-                $ref: "definitions/auth_data.yaml"
+                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.

api/client-server/content-repo.yaml

@@ -163,9 +163,11 @@ paths:
         - Media
   "/download/{serverName}/{mediaId}/{fileName}":
     get:
-      summary: |-
+      summary: Download content from the content repository overriding the file name
-        Download content from the content repository. This is the same as
+      description: |-
-        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:
@@ -233,9 +235,10 @@ paths:
         - Media
   "/thumbnail/{serverName}/{mediaId}":
     get:
-      summary: |-
+      summary: Download a thumbnail of content from the content repository
-        Download a thumbnail of content from the content repository. See the `thumbnailing <#thumbnails>`_
+      description: |-
-        section for more information.
+        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: |
+          description: |-
-            Indicates to the server that it should not attempt to fetch the media if it is deemed
+            Indicates to the server that it should not attempt to fetch
-            remote. This is to prevent routing loops where the server contacts itself. Defaults to
+            the media if it is deemed remote. This is to prevent routing loops
-            true if not provided.
+            where the server contacts itself. Defaults to true if not provided.
       responses:
         200:
           description: "A thumbnail of the requested content."

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: {

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
+                  The new display name for this device. If not given, the
-                    display name is unchanged.
+                  display name is unchanged.
-                example: My other phone
+            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
+                  Additional authentication information for the
-                    user-interactive authentication API.
+                  user-interactive authentication API.
-                "$ref": "definitions/auth_data.yaml"
+                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:

api/client-server/filter.yaml

@@ -119,7 +119,7 @@ paths:
       responses:
         200:
           description: |-
-            "The filter defintion"
+            The filter definition.
           examples:
             application/json: {
                 "room": {

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.

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:

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:

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.

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.

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: {

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

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:

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

api/client-server/redaction.yaml

@@ -65,6 +65,7 @@ paths:
           x-example: "37"
         - in: body
           name: body
+          required: true
           schema:
             type: object
             example: {

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
+                    Additional authentication information for the
-                  user-interactive authentication API. Note that this
+                    user-interactive authentication API. Note that this
-                  information is *not* used to define how the registered user
+                    information is *not* used to define how the registered user
-                  should be authenticated, but is instead used to
+                    should be authenticated, but is instead used to
-                  authenticate the ``register`` call itself.
+                    authenticate the ``register`` call itself.
-                "$ref": "definitions/auth_data.yaml"
+                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.
+                    Additional authentication information for the user-interactive authentication API.
-                "$ref": "definitions/auth_data.yaml"
+                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: |-

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:

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

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.

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 -->

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:

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(