Convert invites to swagger

The whole section reads like a description for the endpoint, and has been replaced by the swagger definition now (rather than at a later stage). All the same information should be kept.

api/server-server/definitions/invite_event.yaml

@@ -0,0 +1,88 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+type: object
+title: Invite Event
+description: An invite event
+allOf:
+  - $ref: "pdu.yaml"
+  - type: object
+    properties:
+      # Note: we override a bunch of parameters to change their descriptions
+      sender:
+        type: string
+        # TODO: Verify/clarify this - it doesn't seem right, given this is a 'regular' invite
+        description: |-
+          The matrix ID of the user who sent the original ``m.room.third_party_invite``
+        example: "@someone:example.org"
+      origin:
+        type: string
+        description: The name of the inviting homeserver
+        example: "matrix.org"
+      origin_server_ts:
+        type: integer
+        format: int64
+        description: A timestamp added by the inviting homeserver
+        example: 1234567890
+      type:
+        type: string
+        description: The value ``m.room.member``
+        example: "m.room.member"
+      state_key:
+        type: string
+        description: The user ID of the invited member
+        example: "@joe:elsewhere.com"
+      content:
+        type: object
+        title: Membership Event Content
+        description: |-
+          The content of the event, matching what is available in the 
+          `Client-Server API`_
+        example: {"membership": "invite"}
+        properties:
+          membership:
+            type: string
+            description: The value ``invite``
+            example: "invite"
+        required: ['membership']
+      auth_events:
+        type: array
+        description: |-
+          An event reference list containing the authorization events that would
+          allow the member to be invited to the room
+        items:
+          type: array
+          maxItems: 2
+          minItems: 2
+          items:
+            - type: string
+              title: Event ID
+              example: "$abc123:matrix.org"
+            - type: object
+              title: Event Hash
+              example: {
+                "sha256": "abase64encodedsha256hashshouldbe43byteslong"
+              }
+              properties:
+                sha256:
+                  type: string
+                  description: The event hash
+                  example: abase64encodedsha256hashshouldbe43byteslong
+              required: ['sha256']
+      redacts:
+        type: string
+        description: Not used
+    required:
+      # Every other field is already flagged as required by the $ref
+      - state_key
+      - unsigned # TODO: apparently this is required?

api/server-server/invites.yaml

@@ -0,0 +1,84 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+swagger: '2.0'
+info:
+  title: "Matrix Federation Invite User To Room API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+produces:
+  - application/json
+paths:
+  "/invite/{roomId}/{eventId}":
+    put:
+      summary: Invites a user to a room
+      description: |-
+        Invites a remote user to a room. Once the event has been 
+        signed by both the inviting homeserver and the invited 
+        homeserver, it can be sent to all of the users in the room.
+      operationId: sendInvite
+      parameters:
+        - in: path
+          name: roomId
+          type: string
+          description: The room ID that the user is being invited to
+          required: true
+          x-example: "!abc123:matrix.org"
+        - in: path
+          name: eventId
+          type: string
+          description: The event ID for the invite event
+          required: true
+          x-example: "$abc123:example.org"
+        - in: body
+          name: body
+          type: object
+          required: true
+          schema:
+            $ref: "definitions/invite_event.yaml"
+          example: {
+            "$ref": "examples/pdu.json",
+            "type": "m.room.member",
+            "content": {
+                "membership": "invite"
+            }
+          }
+      responses:
+        200:
+          description: |-
+            The event with the invited server's signature added. All other fields of the events
+            should remain untouched.
+          schema:
+            type: array
+            minItems: 2
+            maxItems: 2
+            items:
+              - type: integer
+                description: The value ``200``
+                example: 200
+              - $ref: "definitions/invite_event.yaml"
+          examples:
+            application/json: [
+              200,
+              {
+                "$ref": "examples/pdu.json",
+                "type": "m.room.member",
+                "content": {
+                    "membership": "invite"
+                }
+              }
+            ]

specification/server_server_api.rst

@@ -879,65 +879,7 @@ that requested by the requester in the ``v`` parameter).
 Inviting to a room
 ------------------
 
-When a user wishes to invite another user to a local room and the other user is
+{{invites_ss_http_api}}
-on a different server, the inviting server will send a request to the invited
-server::
-
-  PUT .../invite/{roomId}/{eventId}
-
-The required fields in the JSON body are:
-
-======================== ============ =========================================
- Key                      Type         Description
-======================== ============ =========================================
-``room_id``              String       The room ID of the room. Must be the same
-                                      as the room ID specified in the path.
-``event_id``             String       The ID of the event. Must be the same as
-                                      the event ID specified in the path.
-``type``                 String       The value ``m.room.member``.
-``auth_events``          List         An event-reference list containing the
-                                      IDs of the authorization events that
-                                      would allow this member to be invited in
-                                      the room.
-``content``              Object       The content of the event.
-``depth``                Integer      The depth of the event.
-``origin``               String       The name of the inviting homeserver.
-``origin_server_ts``     Integer      A timestamp added by the inviting
-                                      homeserver.
-``prev_events``          List         An event-reference list containing the
-                                      IDs of the immediate predecessor events.
-``sender``               String       The Matrix ID of the user who sent the
-                                      original ``m.room.third_party_invite``.
-``state_key``            String       The Matrix ID of the invited user.
-``signatures``           Object       The signature of the event from the
-                                      origin server.
-``unsigned``             Object       An object containing the properties that
-                                      aren't part of the signature's
-                                      computation.
-======================== ============ =========================================
-
-Where the ``content`` key contains the content for the ``m.room.member`` event
-specified in the `Client-Server API`_. Note that the ``membership`` property of
-the content must be ``invite``.
-
-Upon receiving this request, the invited homeserver will append its signature to
-the event and respond to the request with the following JSON body::
-
- [
-   200,
-   "event": {...}
- ]
-
-Where ``event`` contains the event signed by both homeservers, using the same
-JSON keys as the initial request on ``/invite/{roomId}/{eventId}``. Note that,
-except for the ``signatures`` object (which now contains an additional signature),
-all of the event's keys remain the same as in the event initially provided.
-
-This response format is due to a typo in Synapse, the first implementation of
-Matrix's APIs, and is preserved to maintain compatibility.
-
-Now that the event has been signed by both the inviting homeserver and the
-invited homeserver, it can be sent to all of the users in the room.
 
 Third-party invites
 -------------------