Upgrade Swagger data to OpenAPI 3.1 (#1310)

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

data/api/client-server/knocking.yaml

@@ -11,21 +11,10 @@
 # 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'
+openapi: 3.1.0
 info:
-  title: "Matrix Client-Server Room Knocking API"
-  version: "1.0.0"
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v3
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
+  title: Matrix Client-Server Room Knocking API
+  version: 1.0.0
 paths:
   "/knock/{roomIdOrAlias}":
     post:
@@ -52,74 +41,107 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomIdOrAlias
           description: The room identifier or alias to knock upon.
           required: true
-          x-example: "#monkeys:matrix.org"
-        - in: query
-          type: array
-          items:
+          example: "#monkeys:matrix.org"
+          schema:
             type: string
+        - in: query
           name: server_name
           description: |-
             The servers to attempt to knock on the room through. One of the servers
             must be participating in the room.
-          x-example: ["matrix.org", "elsewhere.ca"]
-        - in: body
-          name: body
-          required: true
+          example:
+            - matrix.org
+            - elsewhere.ca
           schema:
-            type: object
-            properties:
-              reason:
-                type: string
-                description: |-
-                  Optional reason to be included as the `reason` on the subsequent
-                  membership event.
-                example: "Looking for support"
+            type: array
+            items:
+              type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason:
+                  type: string
+                  description: |-
+                    Optional reason to be included as the `reason` on the subsequent
+                    membership event.
+                  example: Looking for support
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             The room has been knocked upon.
 
             The knocked room ID must be returned in the `room_id` field.
-          examples:
-            application/json: {
-              "room_id": "!d41d8cd:matrix.org"
-            }
-          schema:
-            type: object
-            properties:
-              room_id:
-                type: string
-                description: The knocked room ID.
-            required: ["room_id"]
-        403:
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  room_id:
+                    type: string
+                    description: The knocked room ID.
+                required:
+                  - room_id
+              examples:
+                response:
+                  value: {
+                    "room_id": "!d41d8cd:matrix.org"
+                  }
+        "403":
           description: |-
             You do not have permission to knock on the room. A meaningful `errcode`
             and description error text will be returned. Example reasons for rejection are:
 
             - The room is not set up for knocking.
             - The user has been banned from the room.
-          examples:
-            application/json: {
-              "errcode": "M_FORBIDDEN", "error": "You are not allowed to knock on this room."
-            }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
-        404:
-          description: |-
-            The room could not be found or resolved to a room ID.
-          examples:
-            application/json: {
-              "errcode": "M_NOT_FOUND", "error": "That room does not appear to exist."
-            }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
-        429:
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not allowed to knock on this room."
+                  }
+        "404":
+          description: The room could not be found or resolved to a room ID.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "That room does not appear to exist."
+                  }
+        "429":
           description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Room membership
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml