Spec /room/{roomId}/join

This is just replacing the existing spec with a swagger version.

Subsequent pull requests will add 3pid join to this, as well as specing
the invite, leave, ban, and kick endpoints.

api/client-server/v1/membership.yaml

@@ -0,0 +1,68 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Room Membership API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/room/{roomId}/join":
+    post:
+      summary: Start the requesting user participating in a particular room.
+      description: |-
+        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
+        allowed to see all current state events in the room, and all subsequent
+        events associated with the room until the user leaves the room.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room identifier or room alias to join.
+          required: true
+          x-example: "#monkeys:matrix.org"
+      responses:
+        200:
+          description: |-
+            The room has been joined.
+
+            If the room was joined with an room alias, rather than a room ID,
+            the room ID must be returned in the room_id field.
+
+            If the room was joined with a room ID, the room_id field must not be
+            present.
+          examples:
+            application/json: |-
+              {"room_id": "!primates:matrix.org"}
+          schema:
+            type: object  # empty json object
+        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:
+              - The room is invite-only and the user was not invited.
+              - The user has been banned from the room.
+          examples:
+            application/json: |-
+              {"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+  "/join/{roomId}":
+    post:
+      x-alias-for-path: "/room/{roomId}/join"
+      x-alias-link: "post-matrix-client-api-v1-room-roomid-join"

specification/10_client_server_api.rst

@@ -880,43 +880,7 @@ certain operations such as kicking, banning and sending state events. See
 `m.room.power_levels`_ for more information.
 
 
-Joining rooms
-~~~~~~~~~~~~~
-.. TODO-doc What does the home server have to do to join a user to a room?
-   -  See SPEC-30.
-
-Users need to join a room in order to send and receive events in that room. A
-user can join a room by making a request to |/join/<room_alias_or_id>|_ with::
-
-  {}
-
-Alternatively, a user can make a request to |/rooms/<room_id>/join|_ with the
-same request content.  This is only provided for symmetry with the other
-membership APIs: ``/rooms/<room id>/invite`` and ``/rooms/<room id>/leave``. If
-a room alias was specified, it will be automatically resolved to a room ID,
-which will then be joined. The room ID that was joined will be returned in
-response::
-
-  {
-    "room_id": "!roomid:domain"
-  }
-
-The membership state for the joining user can also be modified directly to be
-``join`` by sending the following request to
-``/rooms/<room id>/state/m.room.member/<url encoded user id>``::
-
-  {
-    "membership": "join"
-  }
-
-See the `Room events`_ section for more information on ``m.room.member``.
-
-After the user has joined a room, they will receive subsequent events in that
-room. This room will now appear as an entry in the |initialSync|_ API.
-
-Some rooms enforce that a user is *invited* to a room before they can join that
-room. Other rooms will allow anyone to join the room even if they have not
-received an invite.
+{{membership_http_api}}
 
 Inviting users
 ~~~~~~~~~~~~~~

templating/matrix_templates/sections.py

@@ -90,6 +90,12 @@ class MatrixSections(Sections):
             title_kind="~"
         )
 
+    def render_membership_http_api(self):
+        return self._render_http_api_group(
+            "membership",
+            title_kind="~"
+        )
+
     def render_room_events(self):
         def filterFn(eventType):
             return (