From 7f2813354daecf30bf1a14fa715f88a3511ed5b6 Mon Sep 17 00:00:00 2001
From: Daniel Wagner-Hall <daniel@matrix.org>
Date: Fri, 27 Nov 2015 15:42:21 +0000
Subject: [PATCH] Swaggerify /ban

---
 api/client-server/v1/banning.yaml   | 76 +++++++++++++++++++++++++++++
 specification/client_server_api.rst |  2 +
 2 files changed, 78 insertions(+)
 create mode 100644 api/client-server/v1/banning.yaml

diff --git a/api/client-server/v1/banning.yaml b/api/client-server/v1/banning.yaml
new file mode 100644
index 00000000..e841050f
--- /dev/null
+++ b/api/client-server/v1/banning.yaml
@@ -0,0 +1,76 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Room Banning 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:
+  "/rooms/{roomId}/ban":
+    post:
+      summary: Ban a user in the room.
+      description: |-
+        Ban a user in the room. If the user is currently in the room, also kick them.
+
+        When a user is banned from a room, they may not join it until they are unbanned.
+
+        The caller must have the required power level in order to perform this operation.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room identifier (not alias) from which the user should be banned.
+          required: true
+          x-example: "!e42d8c:matrix.org"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "reason": "Telling unfunny jokes",
+                "user_id": "@cheeky_monkey:matrix.org"
+              }
+            properties:
+              user_id:
+                type: string
+                description: The fully qualified user ID of the user being banned.
+              reason:
+                type: string
+                description: The reason the user has been banned.
+            required: ["user_id"]
+      responses:
+        200:
+          description: The user has been kicked and banned from the room.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object
+        403:
+          description: |-
+            You do not have permission to ban the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
+
+            - The banner is not currently in the room.
+            - The banner's power level is insufficient to ban users from the room.
+          examples:
+            application/json: |-
+              {
+                "errcode": "M_FORBIDDEN",
+                "error": "You do not have a high enough power level to ban from this room."
+              }
diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst
index 402ce753..58d0f1b2 100644
--- a/specification/client_server_api.rst
+++ b/specification/client_server_api.rst
@@ -983,6 +983,8 @@ following values:
 
 {{joining_http_api}}
 
+{{banning_http_api}}
+
 Leaving rooms
 ~~~~~~~~~~~~~
 A user can leave a room to stop receiving events for that room. A user must