Upgrade Swagger data to OpenAPI 3.1 (#1310)

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

changelogs/internal/newsfragments/1310.feature

@@ -0,0 +1 @@
+Upgrade Swagger data to OpenAPI 3.1.

data/api/application-service/ping.yaml

@@ -11,21 +11,12 @@
 # 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 Application Service API"
+  title: Matrix Application Service API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/app/v1
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/ping":
+  /ping:
     post:
       x-addedInMatrixVersion: "1.7"
       summary: Ping the application service
@@ -39,10 +30,9 @@ paths:
       operationId: ping
       security:
         - homeserverAccessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          description: Ping body with optional transaction ID.
             schema:
               type: object
               example: {
@@ -54,10 +44,29 @@ paths:
                   description: |-
                     A transaction ID for the ping, copied directly from the
                     `POST /_matrix/client/v1/appservice/{appserviceId}/ping` call.
+        description: Ping body with optional transaction ID.
       responses:
-        200:
+        "200":
           description: The provided `hs_token` is valid and the ping request was successful.
-          examples:
+          content:
-            application/json: {}
+            application/json:
               schema:
                 type: object
+              examples:
+                response:
+                  value: {}
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/app/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/application-service/protocols.yaml

@@ -11,25 +11,15 @@
 # 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 Application Service API"
+  title: Matrix Application Service API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/app/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/thirdparty/protocol/{protocol}":
     get:
-      summary: Retrieve metadata about a specific protocol that the application service supports.
+      summary: Retrieve metadata about a specific protocol that the application
+        service supports.
       description: |-
         This API is called by the homeserver when it wants to present clients
         with specific information about the various third-party networks that
@@ -40,42 +30,53 @@ paths:
       parameters:
         - in: path
           name: protocol
-          type: string
           description: The protocol ID.
           required: true
-          x-example: "irc"
+          example: irc
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The protocol was found and metadata returned.
+          content:
+            application/json:
               schema:
                 $ref: definitions/protocol.yaml
-        401:
+        "401":
           description: |-
             The homeserver has not supplied credentials to the application service.
             Optional error information can be included in the body of this response.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
                   }
+        "403":
+          description: The credentials supplied by the homeserver were rejected.
+          content:
+            application/json:
               schema:
                 $ref: ../client-server/definitions/errors/error.yaml
-        403:
-          description: |-
-            The credentials supplied by the homeserver were rejected.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
                   }
+        "404":
+          description: No protocol was found with the given path.
+          content:
+            application/json:
               schema:
                 $ref: ../client-server/definitions/errors/error.yaml
-        404:
-          description: No protocol was found with the given path.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
                   }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
   "/thirdparty/user/{protocol}":
     get:
       summary: Retrieve the Matrix User ID of a corresponding third-party user.
@@ -89,102 +90,126 @@ paths:
       parameters:
         - in: path
           name: protocol
-          type: string
           description: The protocol ID.
           required: true
-          x-example: irc
+          example: irc
+          schema:
+            type: string
         - in: query
           name: fields...
-          type: string
           description: |-
             One or more custom fields that are passed to the application
             service to help identify the user.
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The Matrix User IDs found with the given parameters.
+          content:
+            application/json:
               schema:
                 $ref: definitions/user_batch.yaml
-        401:
+        "401":
           description: |-
             The homeserver has not supplied credentials to the application service.
             Optional error information can be included in the body of this response.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
                   }
+        "403":
+          description: The credentials supplied by the homeserver were rejected.
+          content:
+            application/json:
               schema:
                 $ref: ../client-server/definitions/errors/error.yaml
-        403:
-          description: |-
-            The credentials supplied by the homeserver were rejected.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
                   }
+        "404":
+          description: No users were found with the given parameters.
+          content:
+            application/json:
               schema:
                 $ref: ../client-server/definitions/errors/error.yaml
-        404:
-          description: No users were found with the given parameters.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
                   }
-          schema:
-            $ref: ../client-server/definitions/errors/error.yaml
   "/thirdparty/location/{protocol}":
     get:
       summary: Retrieve Matrix-side portal rooms leading to a third-party location.
-      description: |-
+      description: Retrieve a list of Matrix portal rooms that lead to the matched
-        Retrieve a list of Matrix portal rooms that lead to the matched third-party location.
+        third-party location.
       operationId: queryLocationByProtocol
       security:
         - homeserverAccessToken: []
       parameters:
         - in: path
           name: protocol
-          type: string
           description: The protocol ID.
           required: true
-          x-example: irc
+          example: irc
+          schema:
+            type: string
         - in: query
           name: fields...
-          type: string
           description: |-
             One or more custom fields that are passed to the application
             service to help identify the third-party location.
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: At least one portal room was found.
+          content:
+            application/json:
               schema:
                 $ref: definitions/location_batch.yaml
-        401:
+        "401":
           description: |-
             The homeserver has not supplied credentials to the application service.
             Optional error information can be included in the body of this response.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
                   }
+        "403":
+          description: The credentials supplied by the homeserver were rejected.
+          content:
+            application/json:
               schema:
                 $ref: ../client-server/definitions/errors/error.yaml
-        403:
-          description: |-
-            The credentials supplied by the homeserver were rejected.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
                   }
+        "404":
+          description: No mappings were found with the given parameters.
+          content:
+            application/json:
               schema:
                 $ref: ../client-server/definitions/errors/error.yaml
-        404:
-          description: No mappings were found with the given parameters.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
                   }
-          schema:
+  /thirdparty/location:
-            $ref: ../client-server/definitions/errors/error.yaml
-  "/thirdparty/location":
     get:
       summary: Reverse-lookup third-party locations given a Matrix room alias.
       description: |-
@@ -196,84 +221,118 @@ paths:
       parameters:
         - in: query
           name: alias
-          type: string
           description: The Matrix room alias to look up.
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description: |-
+          description: All found third-party locations.
-            All found third-party locations.
+          content:
+            application/json:
               schema:
                 $ref: definitions/location_batch.yaml
-        401:
+        "401":
           description: |-
             The homeserver has not supplied credentials to the application service.
             Optional error information can be included in the body of this response.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
                   }
+        "403":
+          description: The credentials supplied by the homeserver were rejected.
+          content:
+            application/json:
               schema:
                 $ref: ../client-server/definitions/errors/error.yaml
-        403:
-          description: |-
-            The credentials supplied by the homeserver were rejected.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
                   }
+        "404":
+          description: No mappings were found with the given parameters.
+          content:
+            application/json:
               schema:
                 $ref: ../client-server/definitions/errors/error.yaml
-        404:
-          description: No mappings were found with the given parameters.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
                   }
-          schema:
+  /thirdparty/user:
-            $ref: ../client-server/definitions/errors/error.yaml
-  "/thirdparty/user":
     get:
       summary: Reverse-lookup third-party users given a Matrix User ID.
-      description: |-
+      description: Retrieve an array of third-party users from a Matrix User ID.
-        Retrieve an array of third-party users from a Matrix User ID.
       operationId: queryUserByID
       security:
         - homeserverAccessToken: []
       parameters:
         - in: query
           name: userid
-          type: string
           description: The Matrix User ID to look up.
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description: |-
+          description: An array of third-party users.
-            An array of third-party users.
+          content:
+            application/json:
               schema:
                 $ref: definitions/user_batch.yaml
-        401:
+        "401":
           description: |-
             The homeserver has not supplied credentials to the application service.
             Optional error information can be included in the body of this response.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
                   }
+        "403":
+          description: The credentials supplied by the homeserver were rejected.
+          content:
+            application/json:
               schema:
                 $ref: ../client-server/definitions/errors/error.yaml
-        403:
-          description: |-
-            The credentials supplied by the homeserver were rejected.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
                   }
+        "404":
+          description: No mappings were found with the given parameters.
+          content:
+            application/json:
               schema:
                 $ref: ../client-server/definitions/errors/error.yaml
-        404:
-          description: No mappings were found with the given parameters.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
                   }
-          schema:
+servers:
-            $ref: ../client-server/definitions/errors/error.yaml
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/app/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/application-service/query_room.yaml

@@ -12,21 +12,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 Application Service API"
+  title: Matrix Application Service API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/app/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/rooms/{roomAlias}":
     get:
@@ -43,48 +32,75 @@ paths:
       parameters:
         - in: path
           name: roomAlias
-          type: string
           description: The room alias being queried.
           required: true
-          x-example: "#magicforest:example.com"
+          example: "#magicforest:example.com"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: |-
             The application service indicates that this room alias exists. The
             application service MUST have created a room and associated it with
             the queried room alias using the client-server API. Additional
             information about the room such as its name and topic can be set
             before responding.
-          examples:
+          content:
-            application/json: {}
+            application/json:
               schema:
                 type: object
-        401:
+              examples:
+                response:
+                  value: {}
+        "401":
           description: |-
             The homeserver has not supplied credentials to the application service.
             Optional error information can be included in the body of this response.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
                   }
+        "403":
+          description: The credentials supplied by the homeserver were rejected.
+          content:
+            application/json:
               schema:
                 $ref: ../client-server/definitions/errors/error.yaml
-        403:
-          description: |-
-            The credentials supplied by the homeserver were rejected.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
                   }
-          schema:
+        "404":
-            $ref: ../client-server/definitions/errors/error.yaml
-        404:
           description: |-
             The application service indicates that this room alias does not exist.
             Optional error information can be included in the body of this response.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
                   }
-          schema:
+servers:
-            $ref: ../client-server/definitions/errors/error.yaml
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/app/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/application-service/query_user.yaml

@@ -12,21 +12,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 Application Service API"
+  title: Matrix Application Service API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/app/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/users/{userId}":
     get:
@@ -43,45 +32,72 @@ paths:
       parameters:
         - in: path
           name: userId
-          type: string
           description: The user ID being queried.
           required: true
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: |-
             The application service indicates that this user exists. The application
             service MUST create the user using the client-server API.
-          examples:
+          content:
-            application/json: {}
+            application/json:
               schema:
                 type: object
-        401:
+              examples:
+                response:
+                  value: {}
+        "401":
           description: |-
             The homeserver has not supplied credentials to the application service.
             Optional error information can be included in the body of this response.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
                   }
+        "403":
+          description: The credentials supplied by the homeserver were rejected.
+          content:
+            application/json:
               schema:
                 $ref: ../client-server/definitions/errors/error.yaml
-        403:
-          description: |-
-            The credentials supplied by the homeserver were rejected.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
                   }
-          schema:
+        "404":
-            $ref: ../client-server/definitions/errors/error.yaml
-        404:
           description: |-
             The application service indicates that this user does not exist.
             Optional error information can be included in the body of this response.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
                   }
-          schema:
+servers:
-            $ref: ../client-server/definitions/errors/error.yaml
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/app/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/application-service/transactions.yaml

@@ -12,19 +12,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 Application Service API"
+  title: Matrix Application Service API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/app/v1
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/transactions/{txnId}":
     put:
@@ -42,35 +33,59 @@ paths:
       parameters:
         - in: path
           name: txnId
-          type: string
           description: |-
             The transaction ID for this set of events. Homeservers generate
             these IDs and they are used to ensure idempotency of requests.
           required: true
-          x-example: "35"
+          example: "35"
-        - in: body
+          schema:
-          name: body
+            type: string
-          description: Transaction information
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               example: {
                 "events": [
-                {"$ref": "../../event-schemas/examples/m.room.member.yaml"},
+                  {
-                {"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"}
+                    "$ref": "../../event-schemas/examples/m.room.member.yaml"
+                  },
+                  {
+                    "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                  }
                 ]
               }
               properties:
                 events:
                   type: array
-                description: |-
+                  description: A list of events, formatted as per the Client-Server API.
-                  A list of events, formatted as per the Client-Server API.
                   items:
-                  $ref: "../client-server/definitions/client_event.yaml"
+                    $ref: ../client-server/definitions/client_event.yaml
-            required: ["events"]
+              required:
+                - events
+        description: Transaction information
       responses:
-        200:
+        "200":
           description: The transaction was processed successfully.
-          examples:
+          content:
-            application/json: {}
+            application/json:
               schema:
                 type: object
+              examples:
+                response:
+                  value: {}
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/app/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/client-server/account-data.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 Client Config API"
+  title: Matrix Client-Server Client Config API
-  version: "1.0.0"
+  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
 paths:
   "/user/{userId}/account_data/{type}":
     put:
@@ -40,71 +29,85 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           required: true
           description: |-
             The ID of the user to set account data for. The access token must be
             authorized to make requests for this user ID.
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: type
           required: true
           description: |-
             The event type of the account data to set. Custom types should be
             namespaced to avoid clashes.
-          x-example: "org.example.custom.config"
+          example: org.example.custom.config
-        - in: body
+          schema:
-          name: content
+            type: string
-          required: true
+      requestBody:
-          description: |-
+        content:
-            The content of the account data.
+          application/json:
             schema:
               type: object
               example: {
-              "custom_account_data_key": "custom_config_value"}
+                "custom_account_data_key": "custom_config_value"
+              }
+        description: The content of the account data.
+        required: true
       responses:
-        200:
+        "200":
-          description:
+          description: The account data was successfully added.
-            The account data was successfully added.
+          content:
-          examples:
+            application/json:
-            application/json: {}
               schema:
                 type: object
-        400:
+              examples:
+                response:
+                  value: {}
+        "400":
           description: |-
             The request body is not a JSON object. Errcode: `M_BAD_JSON`
             or `M_NOT_JSON`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_JSON",
                     "error": "Content must be a JSON object."
                   }
-          schema:
+        "403":
-            $ref: "../client-server/definitions/errors/error.yaml"
-        403:
           description: |-
             The access token provided is not authorized to modify this user's account 
             data. Errcode: `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "Cannot add account data for other users."
                   }
+        "405":
+          description: |-
+            This `type` of account data is controlled by the server; it cannot be
+            modified by clients. Errcode: `M_BAD_JSON`.
+          content:
+            application/json:
               schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                $ref: ../client-server/definitions/errors/error.yaml
-        405:
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_BAD_JSON",
                     "error": "Cannot set m.fully_read through this API."
                   }
-          description: |-
-            This `type` of account data is controlled by the server; it cannot be
-            modified by clients. Errcode: `M_BAD_JSON`.
-          schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
       tags:
         - User data
     get:
@@ -117,51 +120,61 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           required: true
           description: |-
             The ID of the user to get account data for. The access token must be
             authorized to make requests for this user ID.
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: type
           required: true
           description: |-
             The event type of the account data to get. Custom types should be
             namespaced to avoid clashes.
-          x-example: "org.example.custom.config"
+          example: org.example.custom.config
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description:
+          description: The account data content for the given type.
-            The account data content for the given type.
+          content:
+            application/json:
               schema:
                 type: object
                 example: {
-              "custom_account_data_key": "custom_config_value"}
+                  "custom_account_data_key": "custom_config_value"
-        403:
+                }
+        "403":
           description: |-
             The access token provided is not authorized to retrieve this user's account 
             data. Errcode: `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "Cannot add account data for other users."
                   }
-          schema:
+        "404":
-            $ref: "../client-server/definitions/errors/error.yaml"
-        404:
           description: |-
             No account data has been provided for this user with the given `type`.
             Errcode: `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Account data not found."
                   }
-          schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
       tags:
         - User data
   "/user/{userId}/rooms/{roomId}/account_data/{type}":
@@ -176,79 +189,93 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           required: true
           description: |-
             The ID of the user to set account data for. The access token must be
             authorized to make requests for this user ID.
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: roomId
           required: true
-          description: |-
+          description: The ID of the room to set account data on.
-            The ID of the room to set account data on.
+          example: "!726s6s6q:example.com"
-          x-example: "!726s6s6q:example.com"
+          schema:
-        - in: path
             type: string
+        - in: path
           name: type
           required: true
           description: |-
             The event type of the account data to set. Custom types should be
             namespaced to avoid clashes.
-          x-example: "org.example.custom.room.config"
+          example: org.example.custom.room.config
-        - in: body
+          schema:
-          name: content
+            type: string
-          required: true
+      requestBody:
-          description: |-
+        content:
-            The content of the account data.
+          application/json:
             schema:
               type: object
               example: {
-              "custom_account_data_key": "custom_account_data_value"}
+                "custom_account_data_key": "custom_account_data_value"
+              }
+        description: The content of the account data.
+        required: true
       responses:
-        200:
+        "200":
-          description:
+          description: The account data was successfully added.
-            The account data was successfully added.
+          content:
-          examples:
+            application/json:
-            application/json: {}
               schema:
                 type: object
-        400:
+              examples:
+                response:
+                  value: {}
+        "400":
           description: |-
             The request body is not a JSON object (errcode `M_BAD_JSON` or
             `M_NOT_JSON`), or the given `roomID` is not a valid room ID
             (errcode `M_INVALID_PARAM`).
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_JSON",
                     "error": "Content must be a JSON object."
                   }
-          schema:
+        "403":
-            $ref: "../client-server/definitions/errors/error.yaml"
-        403:
           description: |-
             The access token provided is not authorized to modify this user's account 
             data. Errcode: `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "Cannot add account data for other users."
                   }
-          schema:
+        "405":
-            $ref: "../client-server/definitions/errors/error.yaml"
-        405:
           description: |-
             This `type` of account data is controlled by the server; it cannot be
             modified by clients. Errcode: `M_BAD_JSON`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_BAD_JSON",
                     "error": "Cannot set m.fully_read through this API."
                   }
-          schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
       tags:
         - User data
     get:
@@ -261,65 +288,93 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           required: true
           description: |-
             The ID of the user to get account data for. The access token must be
             authorized to make requests for this user ID.
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: roomId
           required: true
-          description: |-
+          description: The ID of the room to get account data for.
-            The ID of the room to get account data for.
+          example: "!726s6s6q:example.com"
-          x-example: "!726s6s6q:example.com"
+          schema:
-        - in: path
             type: string
+        - in: path
           name: type
           required: true
           description: |-
             The event type of the account data to get. Custom types should be
             namespaced to avoid clashes.
-          x-example: "org.example.custom.room.config"
+          example: org.example.custom.room.config
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description:
+          description: The account data content for the given type.
-            The account data content for the given type.
+          content:
+            application/json:
               schema:
                 type: object
                 example: {
-              "custom_account_data_key": "custom_config_value"}
+                  "custom_account_data_key": "custom_config_value"
-        400:
+                }
-          description: |-
+        "400":
-            The given `roomID` is not a valid room ID. Errcode: `M_INVALID_PARAM`.
+          description: "The given `roomID` is not a valid room ID. Errcode:
+            `M_INVALID_PARAM`."
+          content:
+            application/json:
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_INVALID_PARAM",
                     "error": "@notaroomid:example.org is not a valid room ID."
                   }
-        403:
+        "403":
           description: |-
             The access token provided is not authorized to retrieve this user's account 
             data. Errcode: `M_FORBIDDEN`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "Cannot add account data for other users."
                   }
-          schema:
+        "404":
-            $ref: "../client-server/definitions/errors/error.yaml"
-        404:
           description: |-
             No account data has been provided for this user and this room with the 
             given `type`. Errcode: `M_NOT_FOUND`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Room account data not found."
                   }
-          schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
       tags:
         - User data
+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

data/api/client-server/admin.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 Administration API"
+  title: Matrix Client-Server Administration API
-  version: "1.0.0"
+  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
 paths:
   "/admin/whois/{userId}":
     get:
@@ -41,38 +30,17 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           description: The user to look up.
           required: true
-          x-example: "@peter:rabbit.rocks"
+          example: "@peter:rabbit.rocks"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The lookup was successful.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "user_id": "@peter:rabbit.rocks",
-                "devices": {
-                  "teapot": {
-                    "sessions": [
-                      {
-                        "connections": [
-                          {
-                            "ip": "127.0.0.1",
-                            "last_seen": 1411996332123,
-                            "user_agent": "curl/7.31.0-DEV"
-                          },
-                          {
-                            "ip": "10.0.0.2",
-                            "last_seen": 1411996332123,
-                            "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
-                          }
-                        ]
-                      }
-                    ]
-                  }
-                }
-              }
               schema:
                 type: object
                 properties:
@@ -81,15 +49,15 @@ paths:
                     description: The Matrix user ID of the user.
                   devices:
                     type: object
-                description: |-
+                    description: Each key is an identifier for one of the user's devices.
-                  Each key is an identifier for one of the user's devices.
                     additionalProperties:
                       type: object
                       title: DeviceInfo
                       properties:
                         sessions:
                           type: array
-                      description: A user's sessions (i.e. what they did with an access token from one login).
+                          description: A user's sessions (i.e. what they did with an access token from one
+                            login).
                           items:
                             type: object
                             title: SessionInfo
@@ -111,5 +79,45 @@ paths:
                                     user_agent:
                                       type: string
                                       description: User agent string last seen in the session.
+              examples:
+                response:
+                  value: {
+                    "user_id": "@peter:rabbit.rocks",
+                    "devices": {
+                      "teapot": {
+                        "sessions": [
+                          {
+                            "connections": [
+                              {
+                                "ip": "127.0.0.1",
+                                "last_seen": 1411996332123,
+                                "user_agent": "curl/7.31.0-DEV"
+                              },
+                              {
+                                "ip": "10.0.0.2",
+                                "last_seen": 1411996332123,
+                                "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
+                              }
+                            ]
+                          }
+                        ]
+                      }
+                    }
+                  }
       tags:
         - Server administration
+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

data/api/client-server/administrative_contact.yaml

@@ -12,23 +12,12 @@
 # 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 Account Administrative Contact API"
+  title: Matrix Client-Server Account Administrative Contact API
-  version: "1.0.0"
+  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
 paths:
-  "/account/3pid":
+  /account/3pid:
     get:
       summary: Gets a list of a user's third-party identifiers.
       description: |-
@@ -44,19 +33,10 @@ paths:
       security:
         - accessToken: []
       responses:
-        200:
+        "200":
           description: The lookup was successful.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "threepids": [
-                {
-                  "medium": "email",
-                  "address": "monkey@banana.island",
-                  "validated_at": 1535176800000,
-                  "added_at": 1535336848756
-                }
-              ]
-            }
               schema:
                 type: object
                 properties:
@@ -69,7 +49,9 @@ paths:
                         medium:
                           type: string
                           description: The medium of the third-party identifier.
-                      enum: ["email", "msisdn"]
+                          enum:
+                            - email
+                            - msisdn
                         address:
                           type: string
                           description: The third-party identifier address.
@@ -82,10 +64,25 @@ paths:
                         added_at:
                           type: integer
                           format: int64
-                      description:
+                          description: The timestamp, in milliseconds, when the homeserver associated the
-                        The timestamp, in milliseconds, when the homeserver
+                            third-party identifier with the user.
-                        associated the third-party identifier with the user.
+                      required:
-                  required: ['medium', 'address', 'validated_at', 'added_at']
+                        - medium
+                        - address
+                        - validated_at
+                        - added_at
+              examples:
+                response:
+                  value: {
+                    "threepids": [
+                      {
+                        "medium": "email",
+                        "address": "monkey@banana.island",
+                        "validated_at": 1535176800000,
+                        "added_at": 1535336848756
+                      }
+                    ]
+                  }
       tags:
         - Account management
     post:
@@ -105,15 +102,14 @@ paths:
       deprecated: true
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
               type: object
               properties:
                 three_pid_creds:
-                title: "ThreePidCredentials"
+                  title: ThreePidCredentials
                   type: object
                   description: The third-party credentials to associate with the account.
                   properties:
@@ -132,8 +128,13 @@ paths:
                     sid:
                       type: string
                       description: The session identifier given by the identity server.
-                required: ["client_secret", "id_server", "id_access_token", "sid"]
+                  required:
-            required: ["three_pid_creds"]
+                    - client_secret
+                    - id_server
+                    - id_access_token
+                    - sid
+              required:
+                - three_pid_creds
               example: {
                 "three_pid_creds": {
                   "id_server": "matrix.org",
@@ -142,13 +143,12 @@ paths:
                   "client_secret": "d0nt-T3ll"
                 }
               }
+        required: true
       responses:
-        200:
+        "200":
           description: The addition was successful.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "submit_url": "https://example.org/path/to/submitToken"
-            }
               schema:
                 type: object
                 properties:
@@ -168,19 +168,27 @@ paths:
                       verification will happen without the client's involvement
                       provided the homeserver advertises this specification version
                       in the `/versions` response (ie: r0.5.0).
-                example: "https://example.org/path/to/submitToken"
+                    example: https://example.org/path/to/submitToken
-        403:
+              examples:
+                response:
+                  value: {
+                    "submit_url": "https://example.org/path/to/submitToken"
+                  }
+        "403":
           description: The credentials could not be verified with the identity server.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_THREEPID_AUTH_FAILED",
                     "error": "The third-party credentials could not be verified by the identity server."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Account management
-  "/account/3pid/add":
+  /account/3pid/add:
     post:
       summary: Adds contact information to the user's account.
       description: |-
@@ -194,10 +202,9 @@ paths:
       operationId: add3PID
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
               type: object
               properties:
@@ -206,35 +213,44 @@ paths:
                     Additional authentication information for the
                     user-interactive authentication API.
                   allOf:
-                - $ref: "definitions/auth_data.yaml"
+                    - $ref: definitions/auth_data.yaml
                 client_secret:
                   type: string
                   description: The client secret used in the session with the homeserver.
-                example: "d0nt-T3ll"
+                  example: d0nt-T3ll
                 sid:
                   type: string
                   description: The session identifier given by the homeserver.
-                example: "abc123987"
+                  example: abc123987
-            required: ["client_secret",  "sid"]
+              required:
+                - client_secret
+                - sid
+        required: true
       responses:
-        200:
+        "200":
           description: The addition was successful.
-          examples:
+          content:
-            application/json: {}
+            application/json:
               schema:
                 type: object
-        401:
+              examples:
-          description: |-
+                response:
-            The homeserver requires additional authentication information.
+                  value: {}
+        "401":
+          description: The homeserver requires additional authentication information.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/auth_response.yaml"
+                $ref: definitions/auth_response.yaml
-        429:
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Account management
-  "/account/3pid/bind":
+  /account/3pid/bind:
     post:
       summary: Binds a 3PID to the user's account through an Identity Service.
       description: |-
@@ -248,10 +264,9 @@ paths:
       operationId: bind3PID
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
               type: object
               properties:
@@ -263,32 +278,41 @@ paths:
                   description: The identity server to use.
                 id_access_token:
                   type: string
-                description: |-
+                  description: An access token previously registered with the identity server.
-                  An access token previously registered with the identity server.
                 sid:
                   type: string
                   description: The session identifier given by the identity server.
-            required: ["client_secret", "id_server", "id_access_token", "sid"]
+              required:
+                - client_secret
+                - id_server
+                - id_access_token
+                - sid
               example: {
                 "id_server": "example.org",
                 "id_access_token": "abc123_OpaqueString",
                 "sid": "abc123987",
                 "client_secret": "d0nt-T3ll"
               }
+        required: true
       responses:
-        200:
+        "200":
           description: The addition was successful.
-          examples:
+          content:
-            application/json: {}
+            application/json:
               schema:
                 type: object
-        429:
+              examples:
+                response:
+                  value: {}
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Account management
-  "/account/3pid/delete":
+  /account/3pid/delete:
     post:
       summary: Deletes a third-party identifier from the user's account
       description: |-
@@ -301,10 +325,9 @@ paths:
       operationId: delete3pidFromAccount
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
               type: object
               properties:
@@ -315,32 +338,37 @@ paths:
                     MUST use the `id_server` the identifier was added through. If the
                     homeserver does not know the original `id_server`, it MUST return
                     a `id_server_unbind_result` of `no-support`.
-                example: "example.org"
+                  example: example.org
                 medium:
                   type: string
                   description: The medium of the third-party identifier being removed.
-                enum: ["email", "msisdn"]
+                  enum:
-                example: "email"
+                    - email
+                    - msisdn
+                  example: email
                 address:
                   type: string
                   description: The third-party address being removed.
-                example: "example@example.org"
+                  example: example@example.org
-            required: ['medium', 'address']
+              required:
+                - medium
+                - address
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             The homeserver has disassociated the third-party identifier from the
             user.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
                   id_server_unbind_result:
                     type: string
                     enum:
-                  # XXX: I don't know why, but the order matters here so that "no-support"
+                      - no-support
-                  # doesn't become "no- support" by the renderer.
+                      - success
-                  - "no-support"
-                  - "success"
                     description: |-
                       An indicator as to whether or not the homeserver was able to unbind
                       the 3PID from the identity server. `success` indicates that the
@@ -348,12 +376,12 @@ paths:
                       indicates that the identity server refuses to support the request
                       or the homeserver was not able to determine an identity server to
                       unbind from.
-                example: "success"
+                    example: success
                 required:
                   - id_server_unbind_result
       tags:
         - Account management
-  "/account/3pid/unbind":
+  /account/3pid/unbind:
     post:
       summary: Removes a user's third-party identifier from an identity server.
       description: |-
@@ -366,10 +394,9 @@ paths:
       operationId: unbind3pidFromAccount
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
               type: object
               properties:
@@ -380,46 +407,52 @@ paths:
                     MUST use the `id_server` the identifier was added through. If the
                     homeserver does not know the original `id_server`, it MUST return
                     a `id_server_unbind_result` of `no-support`.
-                example: "example.org"
+                  example: example.org
                 medium:
                   type: string
                   description: The medium of the third-party identifier being removed.
-                enum: ["email", "msisdn"]
+                  enum:
-                example: "email"
+                    - email
+                    - msisdn
+                  example: email
                 address:
                   type: string
                   description: The third-party address being removed.
-                example: "example@example.org"
+                  example: example@example.org
-            required: ['medium', 'address']
+              required:
+                - medium
+                - address
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             The identity server has disassociated the third-party identifier from the
             user.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
                   id_server_unbind_result:
                     type: string
                     enum:
-                  # XXX: I don't know why, but the order matters here so that "no-support"
+                      - no-support
-                  # doesn't become "no- support" by the renderer.
+                      - success
-                  - "no-support"
-                  - "success"
                     description: |-
                       An indicator as to whether or not the identity server was able to unbind
                       the 3PID. `success` indicates that the identity server has unbound the
                       identifier whereas `no-support` indicates that the identity server
                       refuses to support the request or the homeserver was not able to determine
                       an identity server to unbind from.
-                example: "success"
+                    example: success
                 required:
                   - id_server_unbind_result
       tags:
         - Account management
-  "/account/3pid/email/requestToken":
+  /account/3pid/email/requestToken:
     post:
-      summary: Begins the validation process for an email address for association with the user's account.
+      summary: Begins the validation process for an email address for association with
+        the user's account.
       description: |-
         The homeserver must check that the given email address is **not**
         already associated with an account on this homeserver. This API should
@@ -430,49 +463,58 @@ paths:
         the email itself, either by sending a validation email itself or by using
         a service it has control over.
       operationId: requestTokenTo3PIDEmail
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
-            $ref: "definitions/request_email_validation.yaml"
+              $ref: definitions/request_email_validation.yaml
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             An email was sent to the given address. Note that this may be an
             email containing the validation token or it may be informing the
             user of an error.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/request_token_response.yaml"
+                $ref: definitions/request_token_response.yaml
-        403:
+        "400":
-          description: |-
-            The homeserver does not allow the third-party identifier as a
-            contact option.
-          schema:
-            $ref: "definitions/errors/error.yaml"
-          examples:
-            application/json: {
-              "errcode": "M_THREEPID_DENIED",
-              "error": "Third-party identifier is not allowed"
-            }
-        400:
           description: |-
             The third-party identifier is already in use on the homeserver, or
             the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
             can be returned if the server does not trust/support the identity server
             provided in the request.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_THREEPID_IN_USE",
                     "error": "Third-party identifier already in use"
                   }
+        "403":
+          description: |-
+            The homeserver does not allow the third-party identifier as a
+            contact option.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_DENIED",
+                    "error": "Third-party identifier is not allowed"
+                  }
       tags:
         - Account management
-  "/account/3pid/msisdn/requestToken":
+  /account/3pid/msisdn/requestToken:
     post:
-      summary: Begins the validation process for a phone number for association with the user's account.
+      summary: Begins the validation process for a phone number for association with
+        the user's account.
       description: |-
         The homeserver must check that the given phone number is **not**
         already associated with an account on this homeserver. This API should
@@ -483,40 +525,63 @@ paths:
         the phone number itself, either by sending a validation message itself or by using
         a service it has control over.
       operationId: requestTokenTo3PIDMSISDN
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
-            $ref: "definitions/request_msisdn_validation.yaml"
+              $ref: definitions/request_msisdn_validation.yaml
+        required: true
       responses:
-        200:
+        "200":
           description: An SMS message was sent to the given phone number.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/request_token_response.yaml"
+                $ref: definitions/request_token_response.yaml
-        403:
+        "400":
-          description: |-
-            The homeserver does not allow the third-party identifier as a
-            contact option.
-          schema:
-            $ref: "definitions/errors/error.yaml"
-          examples:
-            application/json: {
-              "errcode": "M_THREEPID_DENIED",
-              "error": "Third-party identifier is not allowed"
-            }
-        400:
           description: |-
             The third-party identifier is already in use on the homeserver, or
             the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
             can be returned if the server does not trust/support the identity server
             provided in the request.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_THREEPID_IN_USE",
                     "error": "Third-party identifier already in use"
                   }
+        "403":
+          description: |-
+            The homeserver does not allow the third-party identifier as a
+            contact option.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_DENIED",
+                    "error": "Third-party identifier is not allowed"
+                  }
       tags:
         - Account management
+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

data/api/client-server/appservice_ping.yaml

@@ -11,29 +11,16 @@
 # 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 Application Service Ping API"
+  title: Matrix Client-Server Application Service Ping API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  # Note: this is the same access_token definition used elsewhere in the client
-  # server API, however this expects an access token for an application service.
-  $ref: definitions/security.yaml
 paths:
   "/appservice/{appserviceId}/ping":
     post:
       x-addedInMatrixVersion: "1.7"
-      summary: |-
+      summary: Ask the homeserver to ping the application service to ensure the
-        Ask the homeserver to ping the application service to ensure the connection works.
+        connection works.
       description: |-
         This API asks the homeserver to call the
         [`/_matrix/app/v1/ping`](#post_matrixappv1ping) endpoint on the
@@ -48,31 +35,35 @@ paths:
       operationId: pingAppservice
       parameters:
         - in: path
-          type: string
           name: appserviceId
           description: |-
             The appservice ID of the appservice to ping. This must be the same
             as the appservice whose `as_token` is being used to authenticate the
             request.
           required: true
-          x-example: "telegram"
+          example: telegram
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               properties:
                 transaction_id:
                   type: string
-                description: |-
+                  description: An optional transaction ID that is passed through to the
-                  An optional transaction ID that is passed through to the `/_matrix/app/v1/ping` call.
+                    `/_matrix/app/v1/ping` call.
-                example: "mautrix-go_1683636478256400935_123"
+                  example: mautrix-go_1683636478256400935_123
+        required: true
       security:
         # again, this is the appservice's token - not a typical client's
         - accessToken: []
       responses:
-        200:
+        "200":
           description: The ping was successful.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -85,26 +76,38 @@ paths:
                 required:
                   - duration_ms
               examples:
-            application/json: {"duration_ms": 123}
+                response:
-        400:
+                  value: {
-          description: The application service doesn't have a URL configured. The errcode is `M_URL_NOT_SET`.
+                    "duration_ms": 123
+                  }
+        "400":
+          description: The application service doesn't have a URL configured. The errcode
+            is `M_URL_NOT_SET`.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_URL_NOT_SET",
                     "error": "Application service doesn't have a URL configured"
                   }
-        403:
+        "403":
-          description: The access token used to authenticate the request doesn't belong to an appservice, or belongs to a different appservice than the one in the path. The errcode is `M_FORBIDDEN`.
+          description: The access token used to authenticate the request doesn't belong to
+            an appservice, or belongs to a different appservice than the one in
+            the path. The errcode is `M_FORBIDDEN`.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "Provided access token is not the appservice's as_token"
                   }
-        502:
+        "502":
           description: |-
             The application service returned a bad status, or the connection failed.
             The errcode is `M_BAD_STATUS` or `M_CONNECTION_FAILED`.
@@ -112,6 +115,8 @@ paths:
             For bad statuses, the response may include `status` and `body`
             fields containing the HTTP status code and response body text
             respectively to aid with debugging.
+          content:
+            application/json:
               schema:
                 type: object
                 title: Error
@@ -120,7 +125,9 @@ paths:
                   errcode:
                     type: string
                     description: An error code.
-                enum: [M_BAD_STATUS, M_CONNECTION_FAILED]
+                    enum:
+                      - M_BAD_STATUS
+                      - M_CONNECTION_FAILED
                   error:
                     type: string
                     description: A human-readable error message.
@@ -132,21 +139,44 @@ paths:
                   body:
                     type: string
                     description: The HTTP response body returned by the appservice.
-                example: "{\"errcode\": \"M_UNKNOWN_TOKEN\"}"
+                    example: '{"errcode": "M_UNKNOWN_TOKEN"}'
-            required: ["errcode"]
+                required:
+                  - errcode
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_BAD_STATUS",
                     "error": "Ping returned status 401",
                     "status": 401,
                     "body": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}"
                   }
-        504:
+        "504":
-          description: The connection to the application service timed out. The errcode is `M_CONNECTION_TIMEOUT`.
+          description: The connection to the application service timed out. The errcode is
+            `M_CONNECTION_TIMEOUT`.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_CONNECTION_TIMEOUT",
                     "error": "Connection to application service timed out"
                   }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    # Note: this is the same access_token definition used elsewhere in the client
+    # server API, however this expects an access token for an application service.
+    $ref: definitions/security.yaml

data/api/client-server/appservice_room_directory.yaml

@@ -11,28 +11,14 @@
 # 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 Application Service Room Directory API"
+  title: Matrix Client-Server Application Service Room Directory API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v3
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  # Note: this is the same access_token definition used elsewhere in the client
-  # server API, however this expects an access token for an application service.
-  $ref: definitions/security.yaml
 paths:
   "/directory/list/appservice/{networkId}/{roomId}":
     put:
-      summary: |-
+      summary: Updates a room's visibility in the application service's room directory.
-        Updates a room's visibility in the application service's room directory.
       description: |-
         Updates the visibility of a given room on the application service's room
         directory.
@@ -46,43 +32,69 @@ paths:
       operationId: updateAppserviceRoomDirectoryVisibility
       parameters:
         - in: path
-          type: string
           name: networkId
           description: |-
             The protocol (network) ID to update the room list for. This would
             have been provided by the application service as being listed as
             a supported protocol.
           required: true
-          x-example: "irc"
+          example: irc
-        - in: path
+          schema:
             type: string
+        - in: path
           name: roomId
           description: The room ID to add to the directory.
           required: true
-          x-example: "!somewhere:example.org"
+          example: "!somewhere:example.org"
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               properties:
                 visibility:
                   type: string
-                enum: ["public", "private"]
+                  enum:
+                    - public
+                    - private
                   description: |-
                     Whether the room should be visible (public) in the directory
                     or not (private).
-                example: "public"
+                  example: public
-            required: ['visibility']
+              required:
+                - visibility
+        required: true
       security:
         # again, this is the appservice's token - not a typical client's
         - accessToken: []
       responses:
-        200:
+        "200":
           description: The room's directory visibility has been updated.
+          content:
+            application/json:
               schema:
                 type: object
               examples:
-            application/json: {}
+                response:
+                  value: {}
       tags:
         - Application service room directory management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    # Note: this is the same access_token definition used elsewhere in the client
+    # server API, however this expects an access token for an application service.
+    $ref: definitions/security.yaml

data/api/client-server/banning.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 Banning API"
+  title: Matrix Client-Server Room Banning API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/ban":
     post:
@@ -41,14 +30,15 @@ paths:
         - 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"
+          example: "!e42d8c:matrix.org"
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               example: {
@@ -63,29 +53,37 @@ paths:
                   x-addedInMatrixVersion: "1.1"
                   type: string
                   description: The reason the user has been banned. This will be supplied as the
-                  `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event.
+                    `reason` on the target's updated
-            required: ["user_id"]
+                    [`m.room.member`](/client-server-api/#mroommember) event.
+              required:
+                - user_id
+        required: true
       responses:
-        200:
+        "200":
           description: The user has been kicked and banned from the room.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object
-        403:
+              examples:
+                response:
+                  value: {}
+        "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.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "You do not have a high enough power level to ban from this room."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room membership
   "/rooms/{roomId}/unban":
@@ -101,14 +99,16 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
-          description: The room identifier (not alias) from which the user should be unbanned.
+          description: The room identifier (not alias) from which the user should be
-          required: true
+            unbanned.
-          x-example: "!e42d8c:matrix.org"
-        - in: body
-          name: body
           required: true
+          example: "!e42d8c:matrix.org"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               example: {
@@ -125,26 +125,48 @@ paths:
                   description: |-
                     Optional reason to be included as the `reason` on the subsequent
                     membership event.
-            required: ["user_id"]
+              required:
+                - user_id
+        required: true
       responses:
-        200:
+        "200":
           description: The user has been unbanned from the room.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object
-        403:
+              examples:
+                response:
+                  value: {}
+        "403":
           description: |-
             You do not have permission to unban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
 
             - The unbanner's power level is insufficient to unban users from the room.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "You do not have a high enough power level to unban from this room."
                   }
-          schema:
-            "$ref": "definitions/errors/error.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

data/api/client-server/capabilities.yaml

@@ -11,21 +11,12 @@
 # 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 Capabilities API"
+  title: Matrix Client-Server Capabilities API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v3
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/capabilities":
+  /capabilities:
     get:
       summary: Gets information about the server's capabilities.
       description: |-
@@ -34,34 +25,15 @@ paths:
       operationId: getCapabilities
       security:
         - accessToken: []
-      parameters: []
       responses:
-        200:
+        "200":
-          description:
+          description: The capabilities of the server.
-            The capabilities of the server.
+          content:
-          examples:
+            application/json:
-            application/json: {
-              "capabilities": {
-                "m.change_password": {
-                  "enabled": false
-                },
-                "m.room_versions": {
-                  "default": "1",
-                  "available": {
-                    "1": "stable",
-                    "2": "stable",
-                    "3": "unstable",
-                    "test-version": "unstable"
-                  }
-                },
-                "com.example.custom.ratelimit": {
-                  "max_requests_per_hour": 600
-                }
-              }
-            }
               schema:
                 type: object
-            required: ["capabilities"]
+                required:
+                  - capabilities
                 properties:
                   capabilities:
                     type: object
@@ -72,41 +44,80 @@ paths:
                     additionalProperties:
                       type: object
                     properties:
-                  "m.change_password":
+                      m.change_password:
                         type: object
-                    description: |-
+                        description: Capability to indicate if the user can change their password.
-                      Capability to indicate if the user can change their password.
                         title: ChangePasswordCapability
                         properties:
                           enabled:
                             type: boolean
-                        description: |-
+                            description: True if the user can change their password, false otherwise.
-                          True if the user can change their password, false otherwise.
                             example: false
-                    required: ['enabled']
+                        required:
-                  "m.room_versions":
+                          - enabled
+                      m.room_versions:
                         type: object
                         description: The room versions the server supports.
                         title: RoomVersionsCapability
                         properties:
                           default:
                             type: string
-                        description: |-
+                            description: The default room version the server is using for new rooms.
-                          The default room version the server is using for new rooms.
                             example: "1"
                           available:
                             type: object
-                        description: |-
+                            description: A detailed description of the room versions the server supports.
-                          A detailed description of the room versions the server supports.
                             additionalProperties:
                               type: string
                               title: RoomVersionStability
-                          enum: [stable, unstable]
+                              enum:
+                                - stable
+                                - unstable
                               description: The stability of the room version.
-                    required: ['default', 'available']
+                        required:
-        429:
+                          - default
+                          - available
+              examples:
+                response:
+                  value: {
+                    "capabilities": {
+                      "m.change_password": {
+                        "enabled": false
+                      },
+                      "m.room_versions": {
+                        "default": "1",
+                        "available": {
+                          "1": "stable",
+                          "2": "stable",
+                          "3": "unstable",
+                          "test-version": "unstable"
+                        }
+                      },
+                      "com.example.custom.ratelimit": {
+                        "max_requests_per_hour": 600
+                      }
+                    }
+                  }
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Capabilities
+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

data/api/client-server/create_room.yaml

@@ -12,23 +12,12 @@
 # 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 Creation API"
+  title: Matrix Client-Server Room Creation API
-  version: "1.0.0"
+  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
 paths:
-  "/createRoom":
+  /createRoom:
     post:
       summary: Create a new room
       description: |-
@@ -76,11 +65,9 @@ paths:
       operationId: createRoom
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          description: The desired room configuration.
-          required: true
             schema:
               type: object
               example: {
@@ -95,7 +82,9 @@ paths:
               properties:
                 visibility:
                   type: string
-                enum: ["public", "private"]
+                  enum:
+                    - public
+                    - private
                   description: |-
                     A `public` visibility indicates that the room will be shown
                     in the published room list. A `private` visibility will hide
@@ -146,7 +135,8 @@ paths:
                     properties:
                       id_server:
                         type: string
-                      description: The hostname+port of the identity server which should be used for third-party identifier lookups.
+                        description: The hostname+port of the identity server which should be used for
+                          third-party identifier lookups.
                       id_access_token:
                         type: string
                         description: |-
@@ -161,7 +151,11 @@ paths:
                       address:
                         type: string
                         description: The invitee's third-party identifier.
-                  required: ["id_server", "id_access_token", "medium", "address"]
+                    required:
+                      - id_server
+                      - id_access_token
+                      - medium
+                      - address
                 room_version:
                   type: string
                   description: |-
@@ -201,10 +195,15 @@ paths:
                       content:
                         type: object
                         description: The content of the event.
-                  required: ["type", "content"]
+                    required:
+                      - type
+                      - content
                 preset:
                   type: string
-                enum: ["private_chat", "public_chat", "trusted_private_chat"]
+                  enum:
+                    - private_chat
+                    - public_chat
+                    - trusted_private_chat
                   description: |-
                     Convenience parameter for setting various default state events
                     based on a preset.
@@ -228,23 +227,28 @@ paths:
                     [`m.room.power_levels`](/client-server-api/#mroompower_levels)
                     event content prior to it being sent to the room. Defaults to
                     overriding nothing.
+        description: The desired room configuration.
+        required: true
       responses:
-        200:
+        "200":
           description: Information about the newly created room.
+          content:
+            application/json:
               schema:
                 type: object
                 description: Information about the newly created room.
                 properties:
                   room_id:
                     type: string
-                description: |-
+                    description: The created room's ID.
-                  The created room's ID.
+                required:
-            required: ['room_id']
+                  - room_id
               examples:
-            application/json: {
+                response:
+                  value: {
                     "room_id": "!sefiuhWgwghwWgh:example.com"
                   }
-        400:
+        "400":
           description: |-
             
             The request is invalid. A meaningful `errcode` and description
@@ -266,7 +270,24 @@ paths:
               of a homeserver which does not support the requested room version.
               The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these
               cases.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
       tags:
         - Room creation
+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

data/api/client-server/cross_signing.yaml

@@ -11,23 +11,12 @@
 # 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 Cross Signing API"
+  title: Matrix Client-Server Cross Signing API
-  version: "1.0.0"
+  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
 paths:
-  "/keys/device_signing/upload":
+  /keys/device_signing/upload:
     post:
       x-addedInMatrixVersion: "1.1"
       summary: Upload cross-signing keys.
@@ -38,18 +27,14 @@ paths:
       operationId: uploadCrossSigningKeys
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: keys
+          application/json:
-          description: |-
-            The keys to be published.
-          required: true
             schema:
               type: object
               properties:
                 master_key:
-                description: |-
+                  description: Optional. The user\'s master key.
-                  Optional. The user\'s master key.
                   allOf:
                     - $ref: definitions/cross_signing_key.yaml
                 self_signing_key:
@@ -73,7 +58,7 @@ paths:
                     Additional authentication information for the
                     user-interactive authentication API.
                   allOf:
-                - $ref: "definitions/auth_data.yaml"
+                    - $ref: definitions/auth_data.yaml
               example: {
                 "auth": {
                   "type": "example.type.foo",
@@ -82,16 +67,20 @@ paths:
                 },
                 "master_key": {
                   "user_id": "@alice:example.com",
-                "usage": ["master"],
+                  "usage": [
+                    "master"
+                  ],
                   "keys": {
-                  "ed25519:base64+master+public+key": "base64+master+public+key",
+                    "ed25519:base64+master+public+key": "base64+master+public+key"
                   }
                 },
                 "self_signing_key": {
                   "user_id": "@alice:example.com",
-                "usage": ["self_signing"],
+                  "usage": [
+                    "self_signing"
+                  ],
                   "keys": {
-                  "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key",
+                    "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key"
                   },
                   "signatures": {
                     "@alice:example.com": {
@@ -101,9 +90,11 @@ paths:
                 },
                 "user_signing_key": {
                   "user_id": "@alice:example.com",
-                "usage": ["user_signing"],
+                  "usage": [
+                    "user_signing"
+                  ],
                   "keys": {
-                  "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key",
+                    "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key"
                   },
                   "signatures": {
                     "@alice:example.com": {
@@ -112,13 +103,17 @@ paths:
                   }
                 }
               }
+        description: The keys to be published.
+        required: true
       responses:
-        200:
+        "200":
           description: The provided keys were successfully uploaded.
+          content:
+            application/json:
               schema:
                 type: object
                 example: {}
-        400:
+        "400":
           description: |-
             The input was invalid in some way. This can include one of the
             following error codes:
@@ -126,16 +121,20 @@ paths:
             * `M_INVALID_SIGNATURE`: For example, the self-signing or
               user-signing key had an incorrect signature.
             * `M_MISSING_PARAM`: No master key is available.
+          content:
+            application/json:
               schema:
                 type: object
                 example: {
                   "errcode": "M_INVALID_SIGNATURE",
                   "error": "Invalid signature"
                 }
-        403:
+        "403":
           description: |-
             The public key of one of the keys is the same as one of the user\'s
             device IDs, or the request is not authorized for any other reason.
+          content:
+            application/json:
               schema:
                 type: object
                 example: {
@@ -144,7 +143,7 @@ paths:
                 }
       tags:
         - End-to-end encryption
-  "/keys/signatures/upload":
+  /keys/signatures/upload:
     post:
       x-addedInMatrixVersion: "1.1"
       summary: Upload cross-signing signatures.
@@ -158,13 +157,9 @@ paths:
       operationId: uploadCrossSigningSignatures
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: signatures
+          application/json:
-          description: |-
-            A map from user ID to key ID to signed JSON objects containing the
-            signatures to be published.
-          required: true
             schema:
               type: object
               title: Signatures
@@ -193,7 +188,9 @@ paths:
                   },
                   "base64+master+public+key": {
                     "user_id": "@alice:example.com",
-                  "usage": ["master"],
+                    "usage": [
+                      "master"
+                    ],
                     "keys": {
                       "ed25519:base64+master+public+key": "base64+master+public+key"
                     },
@@ -210,7 +207,9 @@ paths:
                     "keys": {
                       "ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key"
                     },
-                  "usage": ["master"],
+                    "usage": [
+                      "master"
+                    ],
                     "signatures": {
                       "@alice:example.com": {
                         "ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key"
@@ -219,9 +218,15 @@ paths:
                   }
                 }
               }
+        description: |-
+          A map from user ID to key ID to signed JSON objects containing the
+          signatures to be published.
+        required: true
       responses:
-        200:
+        "200":
           description: The provided signatures were processed.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -236,13 +241,25 @@ paths:
                       additionalProperties:
                         type: object
                         title: Error
-                example: {
+                    example:
-                  "@alice:example.com": {
+                      "@alice:example.com":
-                    "HIJKLMN": {
+                        HIJKLMN:
-                      "errcode": "M_INVALID_SIGNATURE",
+                          errcode: M_INVALID_SIGNATURE
-                      "error": "Invalid signature"
+                          error: Invalid signature
-                    }
-                  }
-                }
       tags:
         - End-to-end encryption
+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

data/api/client-server/definitions/push_condition.yaml

@@ -30,7 +30,7 @@ properties:
       the power level event the user needs a minimum power level for. Fields
       must be specified under the `notifications` property in the power level
       event's `content`.
-    x-example: content.body
+    example: content.body
   pattern:
     type: string
     description: |-

data/api/client-server/definitions/push_rule.yaml

@@ -17,9 +17,9 @@ type: object
 properties:
   actions:
     items:
-      type:
+      oneOf:
-      - object
+      - type: object
-      - string
+      - type: string
     type: array
     description: |-
       The actions to perform when this rule is matched.

data/api/client-server/device_management.yaml

@@ -11,34 +11,23 @@
 # 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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Client-Server device management API"
+  title: Matrix Client-Server device management API
-  version: "1.0.0"
+  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
 paths:
-  "/devices":
+  /devices:
     get:
       summary: List registered devices for the current user
-      description: |-
+      description: Gets information about all devices for the current user.
-        Gets information about all devices for the current user.
       operationId: getDevices
       security:
         - accessToken: []
       responses:
-        200:
+        "200":
           description: Device information
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -48,9 +37,10 @@ paths:
                     items:
                       type: object
                       allOf:
-                    - $ref: "definitions/client_device.yaml"
+                        - $ref: definitions/client_device.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "devices": [
                       {
                         "device_id": "QBUAZIFURK",
@@ -65,54 +55,56 @@ paths:
   "/devices/{deviceId}":
     get:
       summary: Get a single device
-      description: |-
+      description: Gets information on a single device, by device id.
-        Gets information on a single device, by device id.
       operationId: getDevice
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: deviceId
           description: The device to retrieve.
           required: true
-          x-example: "QBUAZIFURK"
+          example: QBUAZIFURK
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: Device information
+          content:
+            application/json:
               schema:
                 type: object
                 allOf:
-              - $ref: "definitions/client_device.yaml"
+                  - $ref: definitions/client_device.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "device_id": "QBUAZIFURK",
                     "display_name": "android",
                     "last_seen_ip": "1.2.3.4",
                     "last_seen_ts": 1474491775024
                   }
-        404:
+        "404":
           description: The current user has no device with the given ID.
       tags:
         - Device management
     put:
       summary: Update a device
-      description: |-
+      description: Updates the metadata on the given device.
-        Updates the metadata on the given device.
       operationId: updateDevice
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: deviceId
           description: The device to update.
           required: true
-          x-example: "QBUAZIFURK"
+          example: QBUAZIFURK
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
-          description: New information for the device.
+        content:
+          application/json:
             schema:
               type: object
               properties:
@@ -121,16 +113,22 @@ paths:
                   description: |-
                     The new display name for this device. If not given, the
                     display name is unchanged.
-            example: { "display_name": "My other phone" }
+              example: {
+                "display_name": "My other phone"
+              }
+        description: New information for the device.
+        required: true
       responses:
-        200:
+        "200":
           description: The device was successfully updated.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object  # empty json object
-        404:
+              examples:
+                response:
+                  value: {}
+        "404":
           description: The current user has no device with the given ID.
       tags:
         - Device management
@@ -145,14 +143,15 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: deviceId
           description: The device to delete.
           required: true
-          x-example: "QBUAZIFURK"
+          example: QBUAZIFURK
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               properties:
@@ -161,25 +160,29 @@ paths:
                     Additional authentication information for the
                     user-interactive authentication API.
                   allOf:
-                  - "$ref": "definitions/auth_data.yaml"
+                    - $ref: definitions/auth_data.yaml
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             The device was successfully removed, or had been removed
             previously.
+          content:
+            application/json:
               schema:
                 type: object
               examples:
-            application/json: {
+                response:
-              }
+                  value: {}
-        401:
+        "401":
-          description: |-
+          description: The homeserver requires additional authentication information.
-            The homeserver requires additional authentication information.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/auth_response.yaml"
+                $ref: definitions/auth_response.yaml
       tags:
         - Device management
-  "/delete_devices":
+  /delete_devices:
     post:
       summary: Bulk deletion of devices
       description: |-
@@ -189,10 +192,9 @@ paths:
       operationId: deleteDevices
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
               type: object
               properties:
@@ -202,29 +204,50 @@ paths:
                   items:
                     type: string
                     description: A list of device IDs.
-                example: ["QBUAZIFURK", "AUIECTSRND"]
+                  example:
+                    - QBUAZIFURK
+                    - AUIECTSRND
                 auth:
                   allOf:
-                  - "$ref": "definitions/auth_data.yaml"
+                    - $ref: definitions/auth_data.yaml
                   description: |-
                     Additional authentication information for the
                     user-interactive authentication API.
               required:
                 - devices
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             The devices were successfully removed, or had been removed
             previously.
+          content:
+            application/json:
               schema:
                 type: object
               examples:
-            application/json: {
+                response:
-              }
+                  value: {}
-        401:
+        "401":
-          description: |-
+          description: The homeserver requires additional authentication information.
-            The homeserver requires additional authentication information.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/auth_response.yaml"
+                $ref: definitions/auth_response.yaml
       tags:
         - Device management
+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

data/api/client-server/directory.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 Directory API"
+  title: Matrix Client-Server Directory API
-  version: "1.0.0"
+  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
 paths:
   "/directory/room/{roomAlias}":
     put:
@@ -35,52 +24,64 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomAlias
           description: |
             The room alias to set. Its format is defined
             [in the appendices](/appendices/#room-aliases).
           required: true
-          x-example: "#monkeys:matrix.org"
+          example: "#monkeys:matrix.org"
-        - in: body
+          schema:
-          name: body
+            type: string
-          description: Information about this room alias.
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               properties:
                 room_id:
                   type: string
                   description: The room ID to set.
-            required: ['room_id']
+              required:
+                - room_id
               example: {
                 "room_id": "!abnjk1jdasj98:capuchins.com"
               }
+        description: Information about this room alias.
+        required: true
       responses:
-        200:
+        "200":
           description: The mapping was created.
-          examples:
+          content:
-            application/json: {}
+            application/json:
               schema:
                 type: object
-        400:
+              examples:
+                response:
+                  value: {}
+        "400":
           description: The given `roomAlias` is not a valid room alias.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_INVALID_PARAM",
                     "error": "Room alias invalid"
                   }
-          schema:
+        "409":
-            "$ref": "definitions/errors/error.yaml"
-        409:
           description: A room alias with that name already exists.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_UNKNOWN",
                     "error": "Room alias #monkeys:matrix.org already exists."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room directory
     get:
@@ -91,20 +92,22 @@ paths:
         The server will use the federation API to resolve the alias if the
         domain part of the alias does not correspond to the server's own
         domain.
-
       operationId: getRoomIdByAlias
       parameters:
         - in: path
-          type: string
           name: roomAlias
           description: |
             The room alias. Its format is defined
             [in the appendices](/appendices/#room-aliases).
           required: true
-          x-example: "#monkeys:matrix.org"
+          example: "#monkeys:matrix.org"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The room ID and other information for this alias.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -118,7 +121,8 @@ paths:
                       type: string
                       description: A server which is aware of this room alias.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "room_id": "!abnjk1jdasj98:capuchins.com",
                     "servers": [
                       "capuchins.com",
@@ -126,24 +130,30 @@ paths:
                       "another.com"
                     ]
                   }
-        400:
+        "400":
           description: The given `roomAlias` is not a valid room alias.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_INVALID_PARAM",
                     "error": "Room alias invalid"
                   }
-          schema:
+        "404":
-            "$ref": "definitions/errors/error.yaml"
-        404:
           description: There is no mapped room ID for this room alias.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Room alias #monkeys:matrix.org not found."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room directory
     delete:
@@ -160,36 +170,41 @@ paths:
         canonical alias event are recommended to, in addition to their other relevant permission
         checks, delete the alias and return a successful response even if the user does not
         have permission to update the `m.room.canonical_alias` event.
-
       operationId: deleteRoomAlias
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomAlias
           description: |
             The room alias to remove. Its format is defined
             [in the appendices](/appendices/#room-aliases).
           required: true
-          x-example: "#monkeys:matrix.org"
+          example: "#monkeys:matrix.org"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The mapping was deleted.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object
-        404:
+              examples:
+                response:
+                  value: {}
+        "404":
           description: There is no mapped room ID for this room alias.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Room alias #monkeys:example.org not found."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room directory
   "/rooms/{roomId}/aliases":
@@ -212,29 +227,22 @@ paths:
         Clients are recommended not to display this list of aliases prominently
         as they are not curated, unlike those listed in the `m.room.canonical_alias`
         state event.
-
       operationId: getLocalAliases
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room ID to find local aliases of.
           required: true
-          x-example: "!abc123:example.org"
+          example: "!abc123:example.org"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description: |-
+          description: The list of local aliases for the room.
-            The list of local aliases for the room.
+          content:
-          examples:
+            application/json:
-            application/json: {
-              "aliases": [
-                "#somewhere:example.com",
-                "#another:example.com",
-                "#hat_trick:example.com"
-              ]
-            }
               schema:
                 type: object
                 properties:
@@ -243,28 +251,62 @@ paths:
                     description: The server's local aliases on the room. Can be empty.
                     items:
                       type: string
-            required: ['aliases']
+                required:
-        400:
+                  - aliases
+              examples:
+                response:
+                  value: {
+                    "aliases": [
+                      "#somewhere:example.com",
+                      "#another:example.com",
+                      "#hat_trick:example.com"
+                    ]
+                  }
+        "400":
           description: The given `roomAlias` is not a valid room alias.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_INVALID_PARAM",
                     "error": "Room alias invalid"
                   }
+        "403":
+          description: The user is not permitted to retrieve the list of local aliases for
+            the room.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
-        403:
-          description: The user is not permitted to retrieve the list of local aliases for the room.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "You are not a member of the room."
                   }
-          schema:
+        "429":
-            "$ref": "definitions/errors/error.yaml"
-        429:
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Room directory
+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

data/api/client-server/event_context.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 Event Context API"
+  title: Matrix Client-Server Event Context API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/context/{eventId}":
     get:
@@ -42,29 +31,31 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room to get events from.
           required: true
-          x-example: "!636q39766251:example.com"
+          example: "!636q39766251:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: eventId
           description: The event to get context around.
           required: true
-          x-example: "$f3h4d129462ha:example.com"
+          example: $f3h4d129462ha:example.com
+          schema:
+            type: string
         - in: query
-          type: integer
           name: limit
           description: |-
             The maximum number of context events to return. The limit applies
             to the sum of the `events_before` and `events_after` arrays. The
             requested event ID is always returned in `event` even if `limit` is
             0. Defaults to 10.
-          x-example: 3
+          example: 3
+          schema:
+            type: integer
         - in: query
           name: filter
-          type: string
           description: |-
             A JSON `RoomEventFilter` to filter the returned events with. The
             filter is only applied to `events_before`, `events_after`, and
@@ -73,49 +64,50 @@ paths:
             homeserver prefers.
 
             See [Filtering](/client-server-api/#filtering) for more information.
-          x-example: "66696p746572"
+          example: 66696p746572
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The events and state surrounding the requested event.
+          content:
+            application/json:
               schema:
                 type: object
                 description: The events and state surrounding the requested event.
                 properties:
                   start:
                     type: string
-                description: |-
+                    description: A token that can be used to paginate backwards with.
-                  A token that can be used to paginate backwards with.
                   end:
                     type: string
-                description: |-
+                    description: A token that can be used to paginate forwards with.
-                  A token that can be used to paginate forwards with.
                   events_before:
                     type: array
                     description: |-
                       A list of room events that happened just before the
                       requested event, in reverse-chronological order.
                     items:
-                  $ref: "definitions/client_event.yaml"
+                      $ref: definitions/client_event.yaml
                   event:
-                description: |-
+                    description: Details of the requested event.
-                  Details of the requested event.
                     allOf:
-                  - $ref: "definitions/client_event.yaml"
+                      - $ref: definitions/client_event.yaml
                   events_after:
                     type: array
                     description: |-
                       A list of room events that happened just after the
                       requested event, in chronological order.
                     items:
-                  $ref: "definitions/client_event.yaml"
+                      $ref: definitions/client_event.yaml
                   state:
                     type: array
-                description: |-
+                    description: The state of the room at the last event returned.
-                  The state of the room at the last event returned.
                     items:
-                  $ref: "definitions/client_event.yaml"
+                      $ref: definitions/client_event.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "end": "t29-57_2_0_2",
                     "events_after": [
                       {
@@ -148,3 +140,18 @@ paths:
                   }
       tags:
         - Room participation
+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

data/api/client-server/filter.yaml

@@ -11,20 +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 filter API"
+  title: Matrix Client-Server filter API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-basePath: /_matrix/client/v3
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/user/{userId}/filter":
     post:
@@ -38,49 +28,77 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           required: true
-          description:
+          description: The id of the user uploading the filter. The access token must be
-            The id of the user uploading the filter. The access token must be
             authorized to make requests for this user id.
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
-        - in: body
+          schema:
-          name: filter
+            type: string
-          required: true
+      requestBody:
-          description: The filter to upload.
+        content:
+          application/json:
             schema:
               type: object
               allOf:
-              - $ref: "definitions/sync_filter.yaml"
+                - $ref: definitions/sync_filter.yaml
               example: {
                 "room": {
                   "state": {
-                  "types": ["m.room.*"],
+                    "types": [
-                  "not_rooms": ["!726s6s6q:example.com"]
+                      "m.room.*"
+                    ],
+                    "not_rooms": [
+                      "!726s6s6q:example.com"
+                    ]
                   },
                   "timeline": {
                     "limit": 10,
-                  "types": ["m.room.message"],
+                    "types": [
-                  "not_rooms": ["!726s6s6q:example.com"],
+                      "m.room.message"
-                  "not_senders": ["@spam:example.com"]
+                    ],
+                    "not_rooms": [
+                      "!726s6s6q:example.com"
+                    ],
+                    "not_senders": [
+                      "@spam:example.com"
+                    ]
                   },
                   "ephemeral": {
-                  "types": ["m.receipt", "m.typing"],
+                    "types": [
-                  "not_rooms": ["!726s6s6q:example.com"],
+                      "m.receipt",
-                  "not_senders": ["@spam:example.com"]
+                      "m.typing"
+                    ],
+                    "not_rooms": [
+                      "!726s6s6q:example.com"
+                    ],
+                    "not_senders": [
+                      "@spam:example.com"
+                    ]
                   }
                 },
                 "presence": {
-                "types": ["m.presence"],
+                  "types": [
-                "not_senders": ["@alice:example.com"]
+                    "m.presence"
+                  ],
+                  "not_senders": [
+                    "@alice:example.com"
+                  ]
                 },
                 "event_format": "client",
-              "event_fields": ["type", "content", "sender"]
+                "event_fields": [
+                  "type",
+                  "content",
+                  "sender"
+                ]
               }
+        description: The filter to upload.
+        required: true
       responses:
-        200:
+        "200":
           description: The filter was created.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -91,8 +109,9 @@ paths:
                       with a `{` as this character is used to determine
                       if the filter provided is inline JSON or a previously
                       declared filter by homeservers on some APIs.
-                example: "66696p746572"
+                    example: 66696p746572
-            required: ['filter_id']
+                required:
+                  - filter_id
       tags:
         - Room participation
   "/user/{userId}/filter/{filterId}":
@@ -104,53 +123,95 @@ paths:
       parameters:
         - in: path
           name: userId
-          type: string
+          description: The user ID to download a filter for.
-          description: |-
-            The user ID to download a filter for.
-          x-example: "@alice:example.com"
           required: true
+          example: "@alice:example.com"
+          schema:
+            type: string
         - in: path
           name: filterId
-          type: string
+          description: The filter ID to download.
-          description: |-
-            The filter ID to download.
-          x-example: "66696p746572"
           required: true
+          example: 66696p746572
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description: |-
+          description: The filter definition.
-            The filter definition.
+          content:
+            application/json:
+              schema:
+                type: object
+                allOf:
+                  - $ref: definitions/sync_filter.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "room": {
                       "state": {
-                    "types": ["m.room.*"],
+                        "types": [
-                    "not_rooms": ["!726s6s6q:example.com"]
+                          "m.room.*"
+                        ],
+                        "not_rooms": [
+                          "!726s6s6q:example.com"
+                        ]
                       },
                       "timeline": {
                         "limit": 10,
-                    "types": ["m.room.message"],
+                        "types": [
-                    "not_rooms": ["!726s6s6q:example.com"],
+                          "m.room.message"
-                    "not_senders": ["@spam:example.com"]
+                        ],
+                        "not_rooms": [
+                          "!726s6s6q:example.com"
+                        ],
+                        "not_senders": [
+                          "@spam:example.com"
+                        ]
                       },
                       "ephemeral": {
-                    "types": ["m.receipt", "m.typing"],
+                        "types": [
-                    "not_rooms": ["!726s6s6q:example.com"],
+                          "m.receipt",
-                    "not_senders": ["@spam:example.com"]
+                          "m.typing"
+                        ],
+                        "not_rooms": [
+                          "!726s6s6q:example.com"
+                        ],
+                        "not_senders": [
+                          "@spam:example.com"
+                        ]
                       }
                     },
                     "presence": {
-                  "types": ["m.presence"],
+                      "types": [
-                  "not_senders": ["@alice:example.com"]
+                        "m.presence"
+                      ],
+                      "not_senders": [
+                        "@alice:example.com"
+                      ]
                     },
                     "event_format": "client",
-                "event_fields": ["type", "content", "sender"]
+                    "event_fields": [
+                      "type",
+                      "content",
+                      "sender"
+                    ]
                   }
-          schema:
+        "404":
-            type: object
+          description: Unknown filter.
-            allOf:
-              - $ref: "definitions/sync_filter.yaml"
-        404:
-          description: "Unknown filter."
       tags:
         - Room participation
+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

data/api/client-server/inviting.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 Joining API"
+  title: Matrix Client-Server Room Joining API
-  version: "1.0.0"
+  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
 paths:
   # With an extra " " to disambiguate from the 3pid invite endpoint
   # The extra space makes it sort first for what I'm sure is a good reason.
@@ -47,20 +36,20 @@ paths:
 
         If the user was invited to the room, the homeserver will append a
         `m.room.member` event to the room.
-
       operationId: inviteUser
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room identifier (not alias) to which to invite the user.
           required: true
-          x-example: "!d41d8cd:matrix.org"
+          example: "!d41d8cd:matrix.org"
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               example: {
@@ -77,16 +66,21 @@ paths:
                   description: |-
                     Optional reason to be included as the `reason` on the subsequent
                     membership event.
-            required: ["user_id"]
+              required:
+                - user_id
+        required: true
       responses:
-        200:
+        "200":
-          description: The user has been invited to join the room, or was already invited to the room.
+          description: The user has been invited to join the room, or was already invited
-          examples:
+            to the room.
-            application/json: {
+          content:
-              }
+            application/json:
               schema:
                 type: object
-        400:
+              examples:
+                response:
+                  value: {}
+        "400":
           description: |-
             
             The request is invalid. A meaningful `errcode` and description
@@ -98,9 +92,11 @@ paths:
             - One or more users being invited to the room are residents of a
               homeserver which does not support the requested room version. The
               `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
-        403:
+        "403":
           description: |-
             You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
 
@@ -108,14 +104,36 @@ paths:
             - The invitee is already a member of the room.
             - The inviter is not currently in the room.
             - The inviter's power level is insufficient to invite users to the room.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
-        429:
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "@cheeky_monkey:matrix.org is banned from the room"
+                  }
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $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

data/api/client-server/joining.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 Inviting API"
+  title: Matrix Client-Server Room Inviting API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/join":
     post:
@@ -47,20 +36,21 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room identifier (not alias) to join.
           required: true
-          x-example: "!d41d8cd:matrix.org"
+          example: "!d41d8cd:matrix.org"
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               properties:
                 third_party_signed:
                   allOf:
-                - $ref: "definitions/third_party_signed.yaml"
+                    - $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
@@ -71,24 +61,30 @@ paths:
                   description: |-
                     Optional reason to be included as the `reason` on the subsequent
                     membership event.
-                example: "Looking for support"
+                  example: Looking for support
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             The room has been joined.
 
             The joined room ID must be returned in the `room_id` field.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "room_id": "!d41d8cd:matrix.org"}
               schema:
                 type: object
                 properties:
                   room_id:
                     type: string
                     description: The joined room ID.
-            required: ["room_id"]
+                required:
-        403:
+                  - room_id
+              examples:
+                response:
+                  value: {
+                    "room_id": "!d41d8cd:matrix.org"
+                  }
+        "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:
@@ -96,15 +92,22 @@ paths:
             - The room is invite-only and the user was not invited.
             - The user has been banned from the room.
             - The room is restricted and the user failed to satisfy any of the conditions.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
-        429:
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not invited to this room."
+                  }
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Room membership
   "/join/{roomIdOrAlias}":
@@ -126,29 +129,33 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomIdOrAlias
           description: The room identifier or alias to join.
           required: true
-          x-example: "#monkeys:matrix.org"
+          example: "#monkeys:matrix.org"
-        - in: query
+          schema:
-          type: array
-          items:
             type: string
+        - in: query
           name: server_name
           description: |-
             The servers to attempt to join the room through. One of the servers
             must be participating in the room.
-          x-example: ["matrix.org", "elsewhere.ca"]
+          example:
-        - in: body
+            - matrix.org
-          name: body
+            - elsewhere.ca
-          required: true
+          schema:
+            type: array
+            items:
+              type: string
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               properties:
                 third_party_signed:
                   allOf:
-                  - $ref: "definitions/third_party_signed.yaml"
+                    - $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
@@ -159,24 +166,30 @@ paths:
                   description: |-
                     Optional reason to be included as the `reason` on the subsequent
                     membership event.
-                example: "Looking for support"
+                  example: Looking for support
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             The room has been joined.
 
             The joined room ID must be returned in the `room_id` field.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "room_id": "!d41d8cd:matrix.org"}
               schema:
                 type: object
                 properties:
                   room_id:
                     type: string
                     description: The joined room ID.
-            required: ["room_id"]
+                required:
-        403:
+                  - room_id
+              examples:
+                response:
+                  value: {
+                    "room_id": "!d41d8cd:matrix.org"
+                  }
+        "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:
@@ -184,14 +197,36 @@ paths:
             - The room is invite-only and the user was not invited.
             - The user has been banned from the room.
             - The room is restricted and the user failed to satisfy any of the conditions.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
-        429:
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not invited to this room."
+                  }
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $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

data/api/client-server/keys.yaml

@@ -13,36 +13,21 @@
 # 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 Client Config API"
+  title: Matrix Client-Server Client Config API
-  version: "1.0.0"
+  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
 paths:
-  "/keys/upload":
+  /keys/upload:
     post:
       summary: Upload end-to-end encryption keys.
-      description: |-
+      description: Publishes end-to-end encryption keys for the device.
-        Publishes end-to-end encryption keys for the device.
       operationId: uploadKeys
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: keys
+          application/json:
-          description: |-
-            The keys to be published
-          required: true
             schema:
               type: object
               properties:
@@ -66,25 +51,18 @@ paths:
                     by the [key algorithm](/client-server-api/#key-algorithms).
 
                     May be absent if no new one-time keys are required.
-                example: {
+                  example:
-                  "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
+                    curve25519:AAAAAQ: /qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8
-                  "signed_curve25519:AAAAHg": {
+                    signed_curve25519:AAAAHg:
-                    "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
+                      key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs
-                    "signatures": {
+                      signatures:
-                      "@alice:example.com": {
+                        "@alice:example.com":
-                        "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                          ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw
-                      }
+                    signed_curve25519:AAAAHQ:
-                    }
+                      key: j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw
-                  },
+                      signatures:
-                  "signed_curve25519:AAAAHQ": {
+                        "@alice:example.com":
-                    "key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw",
+                          ed25519:JLAFKJWSCS: IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA
-                    "signatures": {
-                      "@alice:example.com": {
-                        "ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
-                      }
-                    }
-                  }
-                }
                 fallback_keys:
                   x-addedInMatrixVersion: "1.2"
                   # $ref: "definitions/one_time_keys.yaml"
@@ -105,22 +83,21 @@ paths:
                     be included to denote that the key is a fallback key.
 
                     May be absent if a new fallback key is not required.
-                example: {
+                  example:
-                  "curve25519:AAAAAG": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
+                    curve25519:AAAAAG: /qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8
-                  "signed_curve25519:AAAAGj": {
+                    signed_curve25519:AAAAGj:
-                    "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
+                      key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs
-                    "fallback": true,
+                      fallback: true
-                    "signatures": {
+                      signatures:
-                      "@alice:example.com": {
+                        "@alice:example.com":
-                        "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                          ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw
-                      }
+        description: The keys to be published
-                    }
+        required: true
-                  }
-                }
       responses:
-        200:
+        "200":
-          description:
+          description: The provided keys were successfully uploaded.
-            The provided keys were successfully uploaded.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -138,23 +115,18 @@ paths:
                       signed_curve25519: 20
                 required:
                   - one_time_key_counts
-
       tags:
         - End-to-end encryption
-  "/keys/query":
+  /keys/query:
     post:
       summary: Download device identity keys.
-      description: |-
+      description: Returns the current devices and identity keys for the given users.
-        Returns the current devices and identity keys for the given users.
       operationId: queryKeys
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: query
+          application/json:
-          description: |-
-            Query defining the keys to be downloaded
-          required: true
             schema:
               type: object
               properties:
@@ -174,16 +146,18 @@ paths:
                     type: array
                     items:
                       type: string
-                    description: "device ID"
+                      description: device ID
                   example:
                     "@alice:example.com": []
               required:
                 - device_keys
-
+        description: Query defining the keys to be downloaded
+        required: true
       responses:
-        200:
+        "200":
-          description:
+          description: The device information
-            The device information
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -225,30 +199,23 @@ paths:
                             properties:
                               device_display_name:
                                 type: string
-                            description:
+                                description: The display name which the user set on the device.
-                              The display name which the user set on the device.
                     example:
                       "@alice:example.com":
-                    JLAFKJWSCS: {
+                        JLAFKJWSCS:
-                      "user_id": "@alice:example.com",
+                          user_id: "@alice:example.com"
-                      "device_id": "JLAFKJWSCS",
+                          device_id: JLAFKJWSCS
-                      "algorithms": [
+                          algorithms:
-                        "m.olm.v1.curve25519-aes-sha2",
+                            - m.olm.v1.curve25519-aes-sha2
-                        "m.megolm.v1.aes-sha2"
+                            - m.megolm.v1.aes-sha2
-                      ],
+                          keys:
-                      "keys": {
+                            curve25519:JLAFKJWSCS: 3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI
-                        "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
+                            ed25519:JLAFKJWSCS: lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI
-                        "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
+                          signatures:
-                      },
+                            "@alice:example.com":
-                      "signatures": {
+                              ed25519:JLAFKJWSCS: dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA
-                        "@alice:example.com": {
+                          unsigned:
-                          "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
+                            device_display_name: Alice's mobile phone
-                        }
-                      },
-                      "unsigned": {
-                        "device_display_name": "Alice's mobile phone"
-                      }
-                    }
                   master_keys:
                     x-addedInMatrixVersion: "1.1"
                     type: object
@@ -262,15 +229,13 @@ paths:
                     additionalProperties:
                       allOf:
                         - $ref: definitions/cross_signing_key.yaml
-                example: {
+                    example:
-                  "@alice:example.com": {
+                      "@alice:example.com":
-                    "user_id": "@alice:example.com",
+                        user_id: "@alice:example.com"
-                    "usage": ["master"],
+                        usage:
-                    "keys": {
+                          - master
-                      "ed25519:base64+master+public+key": "base64+master+public+key",
+                        keys:
-                    }
+                          ed25519:base64+master+public+key: base64+master+public+key
-                  }
-                }
                   self_signing_keys:
                     x-addedInMatrixVersion: "1.1"
                     type: object
@@ -282,20 +247,16 @@ paths:
                     additionalProperties:
                       allOf:
                         - $ref: definitions/cross_signing_key.yaml
-                example: {
+                    example:
-                  "@alice:example.com": {
+                      "@alice:example.com":
-                    "user_id": "@alice:example.com",
+                        user_id: "@alice:example.com"
-                    "usage": ["self_signing"],
+                        usage:
-                    "keys": {
+                          - self_signing
-                      "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key",
+                        keys:
-                    },
+                          ed25519:base64+self+signing+public+key: base64+self+signing+master+public+key
-                    "signatures": {
+                        signatures:
-                      "@alice:example.com": {
+                          "@alice:example.com":
-                        "ed25519:base64+master+public+key": "signature+of+self+signing+key"
+                            ed25519:base64+master+public+key: signature+of+self+signing+key
-                      }
-                    }
-                  }
-                }
                   user_signing_keys:
                     type: object
                     description: |-
@@ -307,36 +268,28 @@ paths:
                     additionalProperties:
                       allOf:
                         - $ref: definitions/cross_signing_key.yaml
-                example: {
+                    example:
-                  "@alice:example.com": {
+                      "@alice:example.com":
-                    "user_id": "@alice:example.com",
+                        user_id: "@alice:example.com"
-                    "usage": ["user_signing"],
+                        usage:
-                    "keys": {
+                          - user_signing
-                      "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key",
+                        keys:
-                    },
+                          ed25519:base64+user+signing+public+key: base64+user+signing+master+public+key
-                    "signatures": {
+                        signatures:
-                      "@alice:example.com": {
+                          "@alice:example.com":
-                        "ed25519:base64+master+public+key": "signature+of+user+signing+key"
+                            ed25519:base64+master+public+key: signature+of+user+signing+key
-                      }
-                    }
-                  }
-                }
       tags:
         - End-to-end encryption
-  "/keys/claim":
+  /keys/claim:
     post:
       summary: Claim one-time encryption keys.
-      description: |-
+      description: Claims one-time keys for use in pre-key messages.
-        Claims one-time keys for use in pre-key messages.
       operationId: claimKeys
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: query
+          application/json:
-          description: |-
-            Query defining the keys to be claimed
-          required: true
             schema:
               type: object
               properties:
@@ -356,16 +309,19 @@ paths:
                     additionalProperties:
                       type: string
                       description: algorithm
-                    example: "signed_curve25519"
+                      example: signed_curve25519
-                example: {
+                  example:
-                  "@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" }
+                    "@alice:example.com":
-                }
+                      JLAFKJWSCS: signed_curve25519
               required:
                 - one_time_keys
+        description: Query defining the keys to be claimed
+        required: true
       responses:
-        200:
+        "200":
-          description:
+          description: The claimed keys.
-            The claimed keys.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -403,24 +359,19 @@ paths:
                         # See also one_time_key parameter for /keys/upload above.
                         type: object
                         title: OneTimeKeys
-                example: {
+                    example:
-                  "@alice:example.com": {
+                      "@alice:example.com":
-                    "JLAFKJWSCS": {
+                        JLAFKJWSCS:
-                      "signed_curve25519:AAAAHg": {
+                          signed_curve25519:AAAAHg:
-                        "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
+                            key: zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs
-                        "signatures": {
+                            signatures:
-                          "@alice:example.com": {
+                              "@alice:example.com":
-                            "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                                ed25519:JLAFKJWSCS: FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw
-                          }
+                required:
-                        }
+                  - one_time_keys
-                      }
-                    }
-                  }
-                }
-            required: ['one_time_keys']
       tags:
         - End-to-end encryption
-  "/keys/changes":
+  /keys/changes:
     get:
       summary: Query users with recent device key updates.
       description: |-
@@ -439,7 +390,6 @@ paths:
       parameters:
         - in: query
           name: from
-          type: string
           description: |-
             The desired start point of the list. Should be the `next_batch` field
             from a response to an earlier call to [`/sync`](/client-server-api/#get_matrixclientv3sync). Users who have not
@@ -447,21 +397,25 @@ paths:
             existing devices with identity keys since then, will be excluded
             from the results.
           required: true
-          x-example: "s72594_4483_1934"
+          example: s72594_4483_1934
+          schema:
+            type: string
         - in: query
           name: to
-          type: string
           description: |-
             The desired end point of the list. Should be the `next_batch`
             field from a recent call to [`/sync`](/client-server-api/#get_matrixclientv3sync) - typically the most recent
             such call. This may be used by the server as a hint to check its
             caches are up to date.
           required: true
-          x-example: "s75689_5632_2435"
+          example: s75689_5632_2435
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description:
+          description: The list of users who updated their devices.
-            The list of users who updated their devices.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -472,7 +426,9 @@ paths:
                     description: |-
                       The Matrix User IDs of all users who updated their device
                       identity keys.
-                example: ["@alice:example.com", "@bob:example.org"]
+                    example:
+                      - "@alice:example.com"
+                      - "@bob:example.org"
                   left:
                     type: array
                     items:
@@ -481,6 +437,23 @@ paths:
                       The Matrix User IDs of all users who may have left all
                       the end-to-end encrypted rooms they previously shared
                       with the user.
-                example: ["@clara:example.com", "@doug:example.org"]
+                    example:
+                      - "@clara:example.com"
+                      - "@doug:example.org"
       tags:
         - End-to-end encryption
+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

data/api/client-server/kicking.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 Kicking API"
+  title: Matrix Client-Server Room Kicking API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/kick":
     post:
@@ -43,14 +32,15 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room identifier (not alias) from which the user should be kicked.
           required: true
-          x-example: "!e42d8c:matrix.org"
+          example: "!e42d8c:matrix.org"
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               example: {
@@ -66,16 +56,20 @@ paths:
                   description: |-
                     The reason the user has been kicked. This will be supplied as the
                     `reason` on the target's updated [`m.room.member`](/client-server-api/#mroommember) event.
-            required: ["user_id"]
+              required:
+                - user_id
+        required: true
       responses:
-        200:
+        "200":
           description: The user has been kicked from the room.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object
-        403:
+              examples:
+                response:
+                  value: {}
+        "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:
@@ -83,12 +77,30 @@ paths:
             - The kicker is not currently in the room.
             - The kickee is not currently in the room.
             - The kicker's power level is insufficient to kick users from the room.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "You do not have a high enough power level to kick from this room."
                   }
-          schema:
-            "$ref": "definitions/errors/error.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

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"
+  title: Matrix Client-Server Room Knocking API
-  version: "1.0.0"
+  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
 paths:
   "/knock/{roomIdOrAlias}":
     post:
@@ -52,23 +41,27 @@ 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"
+          example: "#monkeys:matrix.org"
-        - in: query
+          schema:
-          type: array
-          items:
             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"]
+          example:
-        - in: body
+            - matrix.org
-          name: body
+            - elsewhere.ca
-          required: true
+          schema:
+            type: array
+            items:
+              type: string
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               properties:
@@ -77,49 +70,78 @@ paths:
                   description: |-
                     Optional reason to be included as the `reason` on the subsequent
                     membership event.
-                example: "Looking for support"
+                  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:
+          content:
-            application/json: {
+            application/json:
-              "room_id": "!d41d8cd:matrix.org"
-            }
               schema:
                 type: object
                 properties:
                   room_id:
                     type: string
                     description: The knocked room ID.
-            required: ["room_id"]
+                required:
-        403:
+                  - 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.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
-              "errcode": "M_FORBIDDEN", "error": "You are not allowed to knock on this room."
+                  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"
+                $ref: definitions/errors/error.yaml
-        404:
-          description: |-
-            The room could not be found or resolved to a room ID.
               examples:
-            application/json: {
+                response:
-              "errcode": "M_NOT_FOUND", "error": "That room does not appear to exist."
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "That room does not appear to exist."
                   }
-          schema:
+        "429":
-            "$ref": "definitions/errors/error.yaml"
-        429:
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $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

data/api/client-server/leaving.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 Leaving API"
+  title: Matrix Client-Server Room Leaving API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/leave":
     post:
@@ -47,14 +36,15 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room identifier to leave.
           required: true
-          x-example: "!nkl290a:matrix.org"
+          example: "!nkl290a:matrix.org"
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               example: {
@@ -67,19 +57,23 @@ paths:
                   description: |-
                     Optional reason to be included as the `reason` on the subsequent
                     membership event.
+        required: true
       responses:
-        200:
+        "200":
-          description: |-
+          description: The room has been left.
-            The room has been left.
+          content:
-          examples:
+            application/json:
-            application/json: {
-              }
               schema:
                 type: object
-        429:
+              examples:
+                response:
+                  value: {}
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Room membership
   "/rooms/{roomId}/forget":
@@ -100,32 +94,54 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room identifier to forget.
           required: true
-          x-example: "!au1ba7o:matrix.org"
+          example: "!au1ba7o:matrix.org"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description: |-
+          description: The room has been forgotten.
-            The room has been forgotten.
+          content:
-          examples:
+            application/json:
-            application/json: {
-              }
               schema:
                 type: object
-        400:
+              examples:
+                response:
+                  value: {}
+        "400":
           description: The user has not left the room
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_UNKNOWN",
                     "error": "User @example:matrix.org is in room !au1ba7o:matrix.org"
                   }
-          schema:
+        "429":
-            "$ref": "definitions/errors/error.yaml"
-        429:
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $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

data/api/client-server/list_joined_rooms.yaml

@@ -11,48 +11,54 @@
 # 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 Listing API"
+  title: Matrix Client-Server Room Listing API
-  version: "1.0.0"
+  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
 paths:
-  "/joined_rooms":
+  /joined_rooms:
     get:
       summary: Lists the user's current rooms.
-      description: |-
+      description: This API returns a list of the user's current rooms.
-        This API returns a list of the user's current rooms.
       operationId: getJoinedRooms
       security:
         - accessToken: []
       responses:
-        200:
+        "200":
           description: A list of the rooms the user is in.
+          content:
+            application/json:
               schema:
                 type: object
-            required: ["joined_rooms"]
+                required:
+                  - joined_rooms
                 properties:
                   joined_rooms:
                     type: array
-                description: |-
+                    description: The ID of each room in which the user has `joined` membership.
-                  The ID of each room in which the user has `joined` membership.
                     items:
                       type: string
               examples:
-            application/json: {
+                response:
+                  value: {
                     "joined_rooms": [
                       "!foo:example.com"
                     ]
                   }
       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

data/api/client-server/list_public_rooms.yaml

@@ -11,56 +11,56 @@
 # 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 Directory API"
+  title: Matrix Client-Server Room Directory API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v3
-consumes:
-  - application/json
-produces:
-  - application/json
 paths:
   "/directory/list/room/{roomId}":
     get:
       summary: Gets the visibility of a room in the directory
-      description: |-
+      description: Gets the visibility of a given room on the server's public room
-        Gets the visibility of a given room on the server's public room directory.
+        directory.
       operationId: getRoomVisibilityOnDirectory
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room ID.
           required: true
-          x-example: "!curbf:matrix.org"
+          example: "!curbf:matrix.org"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The visibility of the room in the directory
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
                   visibility:
                     type: string
-                enum: ['private', 'public']
+                    enum:
+                      - private
+                      - public
                     description: The visibility of the room in the directory.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "visibility": "public"
                   }
-        404:
+        "404":
           description: The room is not known to the server
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Room not found"
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room discovery
     put:
@@ -77,47 +77,56 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room ID.
           required: true
-          x-example: "!curbf:matrix.org"
+          example: "!curbf:matrix.org"
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
-          description: |-
+        content:
-            The new visibility for the room on the room directory.
+          application/json:
             schema:
               type: object
               properties:
                 visibility:
                   type: string
-                enum: ["private", "public"]
+                  enum:
+                    - private
+                    - public
                   description: |-
                     The new visibility setting for the room.
                     Defaults to 'public'.
               example: {
                 "visibility": "public"
               }
+        description: The new visibility for the room on the room directory.
+        required: true
       responses:
-        200:
+        "200":
           description: The visibility was updated, or no change was needed.
-          examples:
+          content:
-            application/json: {}
+            application/json:
               schema:
                 type: object
-        404:
+              examples:
+                response:
+                  value: {}
+        "404":
           description: The room is not known to the server
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Room not found"
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room discovery
-  "/publicRooms":
+  /publicRooms:
     get:
       summary: Lists the public rooms on the server.
       description: |-
@@ -129,28 +138,32 @@ paths:
       parameters:
         - in: query
           name: limit
+          description: Limit the number of results returned.
+          schema:
             type: integer
-          description: |-
-            Limit the number of results returned.
         - in: query
           name: since
-          type: string
           description: |-
             A pagination token from a previous request, allowing clients to
             get the next (or previous) batch of rooms.
             The direction of pagination is specified solely by which token
             is supplied, rather than via an explicit flag.
+          schema:
+            type: string
         - in: query
           name: server
-          type: string
           description: |-
             The server to fetch the public room lists from. Defaults to the
             local server.
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: A list of the rooms on the server.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/public_rooms_response.yaml"
+                $ref: definitions/public_rooms_response.yaml
       tags:
         - Room discovery
     post:
@@ -166,22 +179,20 @@ paths:
       parameters:
         - in: query
           name: server
-          type: string
           description: |-
             The server to fetch the public room lists from. Defaults to the
             local server.
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
-          description: |-
+        content:
-            Options for which rooms to return.
+          application/json:
             schema:
               type: object
               properties:
                 limit:
                   type: integer
-                description: |-
+                  description: Limit the number of results returned.
-                  Limit the number of results returned.
                 since:
                   type: string
                   description: |-
@@ -191,9 +202,8 @@ paths:
                     rather than via an explicit flag.
                 filter:
                   type: object
-                title: "Filter"
+                  title: Filter
-                description: |-
+                  description: Filter to apply to the results.
-                  Filter to apply to the results.
                   properties:
                     generic_search_term:
                       type: string
@@ -221,20 +231,39 @@ paths:
                   description: |-
                     The specific third-party network/protocol to request from the
                     homeserver. Can only be used if `include_all_networks` is false.
-                example: "irc"
+                  example: irc
               example: {
                 "limit": 10,
                 "filter": {
                   "generic_search_term": "foo",
-                "room_types": [null, "m.space"]
+                  "room_types": [
+                    null,
+                    "m.space"
+                  ]
                 },
                 "include_all_networks": false,
                 "third_party_instance_id": "irc"
               }
+        description: Options for which rooms to return.
+        required: true
       responses:
-        200:
+        "200":
           description: A list of the rooms on the server.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/public_rooms_response.yaml"
+                $ref: definitions/public_rooms_response.yaml
       tags:
         - Room discovery
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3

data/api/client-server/login.yaml

@@ -13,23 +13,12 @@
 # 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 Registration and Login API"
+  title: Matrix Client-Server Registration and Login API
-  version: "1.0.0"
+  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
 paths:
-  "/login":
+  /login:
     get:
       summary: Get the supported login types to authenticate users
       description: |-
@@ -37,15 +26,10 @@ paths:
         should pick one of these and supply it as the `type` when logging in.
       operationId: getLoginFlows
       responses:
-        200:
+        "200":
           description: The login types the homeserver supports
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "flows": [
-                {"type": "m.login.password"},
-                {"type": "m.login.token", "get_login_token": true}
-              ]
-            }
               schema:
                 type: object
                 properties:
@@ -55,7 +39,8 @@ paths:
                     items:
                       type: object
                       title: LoginFlow
-                  required: ['type']
+                      required:
+                        - type
                       properties:
                         type:
                           description: |-
@@ -72,10 +57,25 @@ paths:
                             endpoint. Note that supporting the endpoint does not
                             necessarily indicate that the user attempting to log in will
                             be able to generate such a token.
-        429:
+              examples:
+                response:
+                  value: {
+                    "flows": [
+                      {
+                        "type": "m.login.password"
+                      },
+                      {
+                        "type": "m.login.token",
+                        "get_login_token": true
+                      }
+                    ]
+                  }
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Session management
     post:
@@ -92,10 +92,9 @@ paths:
         invalidate any access token previously associated with that device. See
         [Relationship between access tokens and devices](/client-server-api/#relationship-between-access-tokens-and-devices).
       operationId: login
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
               type: object
               example: {
@@ -110,19 +109,25 @@ paths:
               properties:
                 type:
                   type: string
-                enum: ["m.login.password", "m.login.token"]
+                  enum:
+                    - m.login.password
+                    - m.login.token
                   description: The login type being used.
                 identifier:
-                "$ref": "definitions/user_identifier.yaml"
+                  $ref: definitions/user_identifier.yaml
                 user:
                   type: string
-                description: The fully qualified user ID or just local part of the user ID, to log in.  Deprecated in favour of `identifier`.
+                  description: The fully qualified user ID or just local part of the user ID, to
+                    log in.  Deprecated in favour of `identifier`.
                 medium:
                   type: string
-                description: When logging in using a third-party identifier, the medium of the identifier. Must be 'email'.  Deprecated in favour of `identifier`.
+                  description: When logging in using a third-party identifier, the medium of the
+                    identifier. Must be 'email'.  Deprecated in favour of
+                    `identifier`.
                 address:
                   type: string
-                description: Third-party identifier for the user.  Deprecated in favour of `identifier`.
+                  description: Third-party identifier for the user.  Deprecated in favour of
+                    `identifier`.
                 password:
                   type: string
                   description: |-
@@ -130,8 +135,7 @@ paths:
                     password.
                 token:
                   type: string
-                description: |-
+                  description: Required when `type` is `m.login.token`. Part of Token-based login.
-                  Required when `type` is `m.login.token`. Part of Token-based login.
                 device_id:
                   type: string
                   description: |-
@@ -148,30 +152,16 @@ paths:
                     if `device_id` corresponds to a known device.
                 refresh_token:
                   type: boolean
-                description: |-
+                  description: If true, the client supports refresh tokens.
-                  If true, the client supports refresh tokens.
                   x-addedInMatrixVersion: "1.3"
-            required: ["type"]
+              required:
-
+                - type
+        required: true
       responses:
-        200:
+        "200":
           description: The user has been authenticated.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "user_id": "@cheeky_monkey:matrix.org",
-                "access_token": "abc123",
-                "refresh_token": "def456",
-                "expires_in_ms": 60000,
-                "device_id": "GHTYAJCE",
-                "well_known": {
-                  "m.homeserver": {
-                    "base_url": "https://example.org"
-                  },
-                  "m.identity_server": {
-                    "base_url": "https://id.example.org"
-                  }
-                }
-              }
               schema:
                 type: object
                 properties:
@@ -221,34 +211,77 @@ paths:
                       optionally validating the URLs within. This object takes the same
                       form as the one returned from .well-known autodiscovery.
                     allOf:
-                  - "$ref": "definitions/wellknown/full.yaml"
+                      - $ref: definitions/wellknown/full.yaml
-            required: ["access_token", "device_id", "user_id"]
+                required:
-        400:
+                  - access_token
-          description: |-
+                  - device_id
-            Part of the request was invalid. For example, the login type may not be recognised.
+                  - user_id
+              examples:
+                response:
+                  value: {
+                    "user_id": "@cheeky_monkey:matrix.org",
+                    "access_token": "abc123",
+                    "refresh_token": "def456",
+                    "expires_in_ms": 60000,
+                    "device_id": "GHTYAJCE",
+                    "well_known": {
+                      "m.homeserver": {
+                        "base_url": "https://example.org"
+                      },
+                      "m.identity_server": {
+                        "base_url": "https://id.example.org"
+                      }
+                    }
+                  }
+        "400":
+          description: Part of the request was invalid. For example, the login type may
+            not be recognised.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_UNKNOWN",
                     "error": "Bad login type."
                   }
-          schema:
+        "403":
-            "$ref": "definitions/errors/error.yaml"
-        403:
           description: |-
             The login attempt failed. This can include one of the following error codes:
               * `M_FORBIDDEN`: The provided authentication data was incorrect
                 or the requested device ID is the same as a cross-signing key
                 ID.
               * `M_USER_DEACTIVATED`: The user has been deactivated.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN"
                   }
-          schema:
+        "429":
-            "$ref": "definitions/errors/error.yaml"
-        429:
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Session management
+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

data/api/client-server/login_token.yaml

@@ -11,25 +11,15 @@
 # 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 Registration and Login API"
+  title: Matrix Client-Server Registration and Login API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/login/get_token":
+  /login/get_token:
     post:
-      summary: Optional endpoint to generate a single-use, time-limited, `m.login.token` token.
+      summary: Optional endpoint to generate a single-use, time-limited,
+        `m.login.token` token.
       description: |-
         Optional endpoint - the server is not required to implement this endpoint if it does not
         intend to use or support this functionality.
@@ -64,29 +54,29 @@ paths:
       x-addedInMatrixVersion: "1.7"
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
               type: object
               properties:
                 auth:
-                description: |-
+                  description: Additional authentication information for the user-interactive
-                  Additional authentication information for the user-interactive authentication API.
+                    authentication API.
                   allOf:
-                  - $ref: "definitions/auth_data.yaml"
+                    - $ref: definitions/auth_data.yaml
+        required: true
       responses:
-        200:
+        "200":
-          description: The login token an unauthenticated client can use to log in as the requesting user.
+          description: The login token an unauthenticated client can use to log in as the
-          examples:
+            requesting user.
-            application/json: {
+          content:
-              "login_token": "<opaque string>",
+            application/json:
-              "expires_in_ms": 120000
-            }
               schema:
                 type: object
-            required: ["login_token", "expires_in_ms"]
+                required:
+                  - login_token
+                  - expires_in_ms
                 properties:
                   login_token:
                     type: string
@@ -96,23 +86,49 @@ paths:
                     description: |-
                       The time remaining in milliseconds until the homeserver will no longer accept the token. `120000`
                       (2 minutes) is recommended as a default.
-        400:
+              examples:
+                response:
+                  value: {
+                    "login_token": "<opaque string>",
+                    "expires_in_ms": 120000
+                  }
+        "400":
           description: |-
             The request was malformed, or the user does not have an ability to generate tokens for their devices,
             as implied by the [User-Interactive Authentication API](/client-server-api/#user-interactive-authentication-api).
 
             Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token`
             [capability](/client-server-api/#capabilities-negotiation).
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
-        401:
+        "401":
-          description: |-
+          description: The homeserver requires additional authentication information.
-            The homeserver requires additional authentication information.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/auth_response.yaml"
+                $ref: definitions/auth_response.yaml
-        429:
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Session management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/client-server/logout.yaml

@@ -11,23 +11,12 @@
 # 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 Registration and Login API"
+  title: Matrix Client-Server Registration and Login API
-  version: "1.0.0"
+  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
 paths:
-  "/logout":
+  /logout:
     post:
       summary: Invalidates a user access token
       description: |-
@@ -38,14 +27,16 @@ paths:
       security:
         - accessToken: []
       responses:
-        200:
+        "200":
           description: The access token used in the request was successfully invalidated.
+          content:
+            application/json:
               schema:
                 type: object
                 properties: {}
       tags:
         - Session management
-  "/logout/all":
+  /logout/all:
     post:
       summary: Invalidates all access tokens for a user
       description: |-
@@ -64,10 +55,27 @@ paths:
       security:
         - accessToken: []
       responses:
-        200:
+        "200":
           description: The user's access tokens were successfully invalidated.
+          content:
+            application/json:
               schema:
                 type: object
                 properties: {}
       tags:
         - Session management
+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

data/api/client-server/message_pagination.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 Rooms API"
+  title: Matrix Client-Server Rooms API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/messages":
     get:
@@ -41,16 +30,16 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room to get events from.
           required: true
-          x-example: "!636q39766251:example.com"
+          example: "!636q39766251:example.com"
-        - in: query
+          schema:
             type: string
+        - in: query
           name: from
           x-changedInMatrixVersion:
-            1.3: |
+            "1.3": |
               Previously, this field was required and paginating from the first or
               last visible event in the room history wasn't supported.
           description: |-
@@ -66,18 +55,19 @@ paths:
             from the first or last (per the value of the `dir` parameter) visible
             event in the room history for the requesting user.
           required: false
-          x-example: "s345_678_333"
+          example: s345_678_333
-        - in: query
+          schema:
             type: string
+        - in: query
           name: to
           description: |-
             The token to stop returning events at. This token can be obtained from
             a `prev_batch` or `next_batch` token returned by the `/sync` endpoint,
             or from an `end` token returned by a previous request to this endpoint.
           required: false
-        - in: query
+          schema:
             type: string
-          enum: ["b", "f"]
+        - in: query
           name: dir
           description: |-
             The direction to return events from. If this is set to `f`, events
@@ -85,23 +75,29 @@ paths:
             is set to `b`, events will be returned in *reverse* chronological
             order, again starting at `from`.
           required: true
-          x-example: "b"
+          example: b
+          schema:
+            type: string
+            enum:
+              - b
+              - f
         - in: query
-          type: integer
           name: limit
-          description: |-
+          description: "The maximum number of events to return. Default: 10."
-            The maximum number of events to return. Default: 10.
+          example: "3"
-          x-example: "3"
+          schema:
+            type: integer
         - in: query
-          type: string
           name: filter
-          description: |-
+          description: A JSON RoomEventFilter to filter returned events with.
-            A JSON RoomEventFilter to filter returned events with.
+          example: '{"contains_url":true}'
-          x-example: |-
+          schema:
-            {"contains_url":true}
+            type: string
       responses:
-        200:
+        "200":
           description: A list of messages with a new token to request more.
+          content:
+            application/json:
               schema:
                 type: object
                 description: A list of messages with a new token to request more.
@@ -133,7 +129,7 @@ paths:
                       are available. Clients should continue to paginate until no `end` property
                       is returned.
                     items:
-                  "$ref": "definitions/client_event.yaml"
+                      $ref: definitions/client_event.yaml
                   state:
                     type: array
                     description: |-
@@ -146,31 +142,47 @@ paths:
                       sent to the client in prior calls to this endpoint, assuming
                       the membership of those members has not changed.
                     items:
-                  $ref: "definitions/client_event.yaml"
+                      $ref: definitions/client_event.yaml
-            required: [start, chunk]
+                required:
+                  - start
+                  - chunk
               examples:
-            application/json:
+                response:
-              {
+                  value: {
                     "start": "t47429-4392820_219380_26003_2265",
                     "end": "t47409-4357353_219380_26003_2265",
-                "chunk":
+                    "chunk": [
-                  [
                       {
                         "room_id": "!636q39766251:example.com",
-                      "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
+                        "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
                       },
                       {
                         "room_id": "!636q39766251:example.com",
-                      "$ref": "../../event-schemas/examples/m.room.name.yaml",
+                        "$ref": "../../event-schemas/examples/m.room.name.yaml"
                       },
                       {
                         "room_id": "!636q39766251:example.com",
-                      "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml",
+                        "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml"
-                    },
+                      }
-                  ],
+                    ]
                   }
-        403:
+        "403":
-          description: >
+          description: |
             You aren't a member of the room.
       tags:
         - Room participation
+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

data/api/client-server/notifications.yaml

@@ -11,24 +11,12 @@
 # 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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Client-Server Notifications API"
+  title: Matrix Client-Server Notifications API
-  version: "1.0.0"
+  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
 paths:
-  "/notifications":
+  /notifications:
     get:
       summary: Gets a list of events that the user has been notified about
       description: |-
@@ -39,52 +27,40 @@ paths:
         - accessToken: []
       parameters:
         - in: query
-          type: string
           name: from
           description: |-
             Pagination token to continue from. This should be the `next_token`
             returned from an earlier call to this endpoint.
           required: false
-          x-example: "xxxxx"
+          example: xxxxx
+          schema:
+            type: string
         - in: query
-          type: integer
           name: limit
           description: Limit on the number of events to return in this request.
           required: false
-          x-example: 20
+          example: 20
+          schema:
+            type: integer
         - in: query
           name: only
-          type: string
           description: |-
             Allows basic filtering of events returned. Supply `highlight`
             to return only events where the notification had the highlight
             tweak set.
           required: false
-          x-example: "highlight"
+          example: highlight
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: A batch of events is being returned
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "next_token": "abcdef",
-                "notifications": [
-                  {
-                    "actions": [
-                      "notify"
-                    ],
-                    "profile_tag": "hcbvkzxhcvb",
-                    "read": true,
-                    "room_id": "!abcdefg:example.com",
-                    "ts": 1475508881945,
-                    "event": {
-                      "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
-                    }
-                  }
-                ]
-              }
               schema:
                 type: object
-            required: ["notifications"]
+                required:
+                  - notifications
                 properties:
                   next_token:
                     type: string
@@ -96,7 +72,12 @@ paths:
                     type: array
                     items:
                       type: object
-                  required: ["actions", "event", "read", "room_id", "ts"]
+                      required:
+                        - actions
+                        - event
+                        - read
+                        - room_id
+                        - ts
                       title: Notification
                       properties:
                         actions:
@@ -105,14 +86,14 @@ paths:
                             The action(s) to perform when the conditions for this rule are met.
                             See [Push Rules: API](/client-server-api/#push-rules-api).
                           items:
-                        type:
+                            oneOf:
-                        - object
+                              - type: object
-                        - string
+                              - type: string
                         event:
                           title: Event
                           description: The Event object for the event that triggered the notification.
                           allOf:
-                        - "$ref": "definitions/client_event_without_room_id.yaml"
+                            - $ref: definitions/client_event_without_room_id.yaml
                         profile_tag:
                           type: string
                           description: The profile tag of the rule that matched this event.
@@ -131,5 +112,39 @@ paths:
                             The unix timestamp at which the event notification was sent,
                             in milliseconds.
                     description: The list of events that triggered notifications.
+              examples:
+                response:
+                  value: {
+                    "next_token": "abcdef",
+                    "notifications": [
+                      {
+                        "actions": [
+                          "notify"
+                        ],
+                        "profile_tag": "hcbvkzxhcvb",
+                        "read": true,
+                        "room_id": "!abcdefg:example.com",
+                        "ts": 1475508881945,
+                        "event": {
+                          "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                        }
+                      }
+                    ]
+                  }
       tags:
         - Push notifications
+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

data/api/client-server/old_sync.yaml

@@ -11,23 +11,12 @@
 # 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 Sync API"
+  title: Matrix Client-Server Sync API
-  version: "1.0.0"
+  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
 paths:
-  "/events":
+  /events:
     get:
       summary: Listen on the event stream.
       description: |-
@@ -43,30 +32,26 @@ paths:
         - accessToken: []
       parameters:
         - in: query
-          type: string
           name: from
           description: |-
             The token to stream from. This token is either from a previous
             request to this API or from the initial sync API.
           required: false
-          x-example: "s3456_9_0"
+          example: s3456_9_0
+          schema:
+            type: string
         - in: query
-          type: integer
           name: timeout
           description: The maximum time in milliseconds to wait for an event.
           required: false
-          x-example: "35000"
+          example: "35000"
+          schema:
+            type: integer
       responses:
-        200:
+        "200":
-          description: "The events received, which may be none."
+          description: The events received, which may be none.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "start": "s3456_9_0",
-                "end": "s3457_9_0",
-                "chunk": [
-                  {"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"}
-                ]
-              }
               schema:
                 type: object
                 properties:
@@ -82,15 +67,26 @@ paths:
                       token should be used in the next request to `/events`.
                   chunk:
                     type: array
-                description: "An array of events."
+                    description: An array of events.
                     items:
-                  $ref: "definitions/client_event.yaml"
+                      $ref: definitions/client_event.yaml
-        400:
+              examples:
-          description: "Bad pagination `from` parameter."
+                response:
+                  value: {
+                    "start": "s3456_9_0",
+                    "end": "s3457_9_0",
+                    "chunk": [
+                      {
+                        "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                      }
+                    ]
+                  }
+        "400":
+          description: Bad pagination `from` parameter.
       tags:
         - Room participation
       deprecated: true
-  "/initialSync":
+  /initialSync:
     get:
       summary: Get the user's current state.
       description: |-
@@ -106,13 +102,13 @@ paths:
         - accessToken: []
       parameters:
         - in: query
-          type: integer
           name: limit
           description: The maximum number of messages to return for each room.
           required: false
-          x-example: "2"
+          example: "2"
+          schema:
+            type: integer
         - in: query
-          type: boolean
           name: archived
           description: |-
             Whether to include rooms that the user has left. If `false` then
@@ -120,76 +116,14 @@ paths:
             included. If set to `true` then rooms that the user has left are
             included as well. By default this is `false`.
           required: false
-          x-example: "true"
+          example: "true"
+          schema:
+            type: boolean
       responses:
-        200:
+        "200":
           description: The user's current state.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                  "end": "s3456_9_0",
-                  "presence": [
-                      {"$ref": "../../event-schemas/examples/m.presence.yaml"}
-                  ],
-                  "account_data": [
-                    {
-                      "type": "org.example.custom.config",
-                      "content": {
-                        "custom_config_key": "custom_config_value"
-                      }
-                    }
-                  ],
-                  "rooms": [
-                      {
-                          "membership": "join",
-                          "messages": {
-                              "chunk": [
-                                  {
-                                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                    "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
-                                  },
-                                  {
-                                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                    "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml"
-                                  }
-                              ],
-                              "end": "s3456_9_0",
-                              "start": "t44-3453_9_0"
-                          },
-                          "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                          "state": [
-                              {
-                                "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                "$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
-                              },
-                              {
-                                "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                "$ref": "../../event-schemas/examples/m.room.member.yaml"
-                              },
-                              {
-                                "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                "$ref": "../../event-schemas/examples/m.room.create.yaml"
-                              },
-                              {
-                                "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                "$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
-                              }
-                          ],
-                          "visibility": "private",
-                          "account_data": [
-                            {
-                              "type": "m.tag",
-                              "content": {"tags": {"work": {"order": 1}}}
-                            },
-                            {
-                              "type": "org.example.custom.room.config",
-                              "content": {
-                                "custom_config_key": "custom_config_value"
-                              }
-                            }
-                          ]
-                      }
-                  ]
-              }
               schema:
                 type: object
                 properties:
@@ -203,7 +137,7 @@ paths:
                     type: array
                     description: A list of presence events.
                     items:
-                  $ref: "definitions/client_event.yaml"
+                      $ref: definitions/client_event.yaml
                   rooms:
                     type: array
                     items:
@@ -212,21 +146,25 @@ paths:
                       properties:
                         room_id:
                           type: string
-                      description: "The ID of this room."
+                          description: The ID of this room.
                         membership:
                           type: string
-                      description: "The user's membership state in this room."
+                          description: The user's membership state in this room.
-                      enum: ["invite", "join", "leave", "ban"]
+                          enum:
+                            - invite
+                            - join
+                            - leave
+                            - ban
                         invite:
                           type: object
-                        title: "InviteEvent"
+                          title: InviteEvent
-                        description: "The invite event if `membership` is `invite`"
+                          description: The invite event if `membership` is `invite`
                           allOf:
-                          - $ref: "definitions/client_event.yaml"
+                            - $ref: definitions/client_event.yaml
                         messages:
                           type: object
                           title: PaginationChunk
-                      description: "The pagination chunk for this room."
+                          description: The pagination chunk for this room.
                           properties:
                             start:
                               type: string
@@ -254,8 +192,10 @@ paths:
                                 messages that preceded them leaving. This array
                                 will consist of at most `limit` elements.
                               items:
-                            $ref: "definitions/client_event.yaml"
+                                $ref: definitions/client_event.yaml
-                      required: ["end", "chunk"]
+                          required:
+                            - end
+                            - chunk
                         state:
                           type: array
                           description: |-
@@ -264,10 +204,12 @@ paths:
                             user has left the room this will be the state of the
                             room when they left it.
                           items:
-                        $ref: "definitions/client_event.yaml"
+                            $ref: definitions/client_event.yaml
                         visibility:
                           type: string
-                      enum: ["private", "public"]
+                          enum:
+                            - private
+                            - public
                           description: |-
                             Whether this room is visible to the `/publicRooms` API
                             or not."
@@ -277,19 +219,98 @@ paths:
                             The private data that this user has attached to
                             this room.
                           items:
-                        $ref: "definitions/client_event.yaml"
+                            $ref: definitions/client_event.yaml
-                  required: ["room_id", "membership"]
+                      required:
+                        - room_id
+                        - membership
                   account_data:
                     type: array
-                description: |-
+                    description: The global private data created by this user.
-                  The global private data created by this user.
                     items:
                       title: Event
                       type: object
                       allOf:
-                    - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
+                        - $ref: ../../event-schemas/schema/core-event-schema/event.yaml
-            required: ["end", "rooms", "presence"]
+                required:
-        404:
+                  - end
+                  - rooms
+                  - presence
+              examples:
+                response:
+                  value: {
+                    "end": "s3456_9_0",
+                    "presence": [
+                      {
+                        "$ref": "../../event-schemas/examples/m.presence.yaml"
+                      }
+                    ],
+                    "account_data": [
+                      {
+                        "type": "org.example.custom.config",
+                        "content": {
+                          "custom_config_key": "custom_config_value"
+                        }
+                      }
+                    ],
+                    "rooms": [
+                      {
+                        "membership": "join",
+                        "messages": {
+                          "chunk": [
+                            {
+                              "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                              "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                            },
+                            {
+                              "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                              "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml"
+                            }
+                          ],
+                          "end": "s3456_9_0",
+                          "start": "t44-3453_9_0"
+                        },
+                        "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                        "state": [
+                          {
+                            "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                            "$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
+                          },
+                          {
+                            "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                            "$ref": "../../event-schemas/examples/m.room.member.yaml"
+                          },
+                          {
+                            "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                            "$ref": "../../event-schemas/examples/m.room.create.yaml"
+                          },
+                          {
+                            "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                            "$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
+                          }
+                        ],
+                        "visibility": "private",
+                        "account_data": [
+                          {
+                            "type": "m.tag",
+                            "content": {
+                              "tags": {
+                                "work": {
+                                  "order": 1
+                                }
+                              }
+                            }
+                          },
+                          {
+                            "type": "org.example.custom.room.config",
+                            "content": {
+                              "custom_config_key": "custom_config_value"
+                            }
+                          }
+                        ]
+                      }
+                    ]
+                  }
+        "404":
           description: There is no avatar URL for this user or this user does not exist.
       tags:
         - Room participation
@@ -310,20 +331,42 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: eventId
           description: The event ID to get.
           required: true
-          x-example: "$asfDuShaf7Gafaw:matrix.org"
+          example: $asfDuShaf7Gafaw:matrix.org
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The full event.
-          examples:
+          content:
-            application/json: {"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"}
+            application/json:
               schema:
-            $ref: "definitions/client_event.yaml"
+                $ref: definitions/client_event.yaml
-        404:
+              examples:
-          description: The event was not found or you do not have permission to read this event.
+                response:
+                  value: {
+                    "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                  }
+        "404":
+          description: The event was not found or you do not have permission to read this
+            event.
       tags:
         - Room participation
       deprecated: true
+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

data/api/client-server/openid.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 OpenID API"
+  title: Matrix Client-Server OpenID API
-  version: "1.0.0"
+  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
 paths:
   "/user/{userId}/openid/request_token":
     post:
@@ -44,40 +33,62 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           description: |-
             The user to request an OpenID token for. Should be the user who
             is authenticated for the request.
           required: true
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
-        - in: body
+          schema:
-          name: body
+            type: string
-          description: An empty object. Reserved for future expansion.
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               example: {}
+        description: An empty object. Reserved for future expansion.
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             OpenID token information. This response is nearly compatible with the
             response documented in the
             [OpenID Connect 1.0 Specification](http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse)
             with the only difference being the lack of an `id_token`. Instead,
             the Matrix homeserver's name is provided.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/openid_token.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "access_token": "SomeT0kenHere",
                     "token_type": "Bearer",
                     "matrix_server_name": "example.com",
-              "expires_in": 3600,
+                    "expires_in": 3600
                   }
-          schema:
+        "429":
-            $ref: "definitions/openid_token.yaml"
-        429:
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - OpenID
+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

data/api/client-server/peeking_events.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 Sync Guest API"
+  title: Matrix Client-Server Sync Guest API
-  version: "1.0.0"
+  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
 paths:
   # With an extra " " to disambiguate from the getEvents endpoint
   # The extra space makes it sort first for what I'm sure is a good reason.
@@ -48,40 +37,33 @@ paths:
         - accessToken: []
       parameters:
         - in: query
-          type: string
           name: from
           description: |-
             The token to stream from. This token is either from a previous
             request to this API or from the initial sync API.
           required: false
-          x-example: "s3456_9_0"
+          example: s3456_9_0
+          schema:
+            type: string
         - in: query
-          type: integer
           name: timeout
           description: The maximum time in milliseconds to wait for an event.
           required: false
-          x-example: "35000"
+          example: "35000"
+          schema:
+            type: integer
         - in: query
-          type: string
           name: room_id
-          description: |-
+          description: The room ID for which events should be returned.
-            The room ID for which events should be returned.
+          example:
-          x-example:
             - "!somewhere:over.the.rainbow"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description: "The events received, which may be none."
+          description: The events received, which may be none.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "start": "s3456_9_0",
-                "end": "s3457_9_0",
-                "chunk": [
-                  {
-                    "room_id": "!somewhere:over.the.rainbow",
-                    "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
-                  }
-                ]
-              }
               schema:
                 type: object
                 properties:
@@ -97,13 +79,40 @@ paths:
                       token should be used in the next request to `/events`.
                   chunk:
                     type: array
-                description: "An array of events."
+                    description: An array of events.
                     items:
                       type: object
                       title: Event
                       allOf:
-                    - "$ref": "definitions/client_event.yaml"
+                        - $ref: definitions/client_event.yaml
-        400:
+              examples:
-          description: "Bad pagination `from` parameter."
+                response:
+                  value: {
+                    "start": "s3456_9_0",
+                    "end": "s3457_9_0",
+                    "chunk": [
+                      {
+                        "room_id": "!somewhere:over.the.rainbow",
+                        "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                      }
+                    ]
+                  }
+        "400":
+          description: Bad pagination `from` parameter.
       tags:
         - Room participation
+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

data/api/client-server/presence.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 Presence API"
+  title: Matrix Client-Server Presence API
-  version: "1.0.0"
+  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
 paths:
   "/presence/{userId}/status":
     put:
@@ -40,15 +29,15 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           description: The user whose presence state to update.
           required: true
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
-        - in: body
+          schema:
-          name: presenceState
+            type: string
-          description: The updated presence state.
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               example: {
@@ -58,54 +47,64 @@ paths:
               properties:
                 presence:
                   type: string
-                enum: ["online", "offline", "unavailable"]
+                  enum:
+                    - online
+                    - offline
+                    - unavailable
                   description: The new presence state.
                 status_msg:
                   type: string
                   description: The status message to attach to this state.
-            required: ["presence"]
+              required:
+                - presence
+        description: The updated presence state.
+        required: true
       responses:
-        200:
+        "200":
           description: The new presence state was set.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object  # empty json object
-        429:
+              examples:
+                response:
+                  value: {}
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Presence
     get:
       summary: Get this user's presence state.
-      description: |-
+      description: Get the given user's presence state.
-        Get the given user's presence state.
       operationId: getPresence
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           description: The user whose presence state to get.
           required: true
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The presence state for this user.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "presence": "unavailable",
-                "last_active_ago": 420845
-              }
               schema:
                 type: object
                 properties:
                   presence:
                     type: string
-                enum: ["online", "offline", "unavailable"]
+                    enum:
+                      - online
+                      - offline
+                      - unavailable
                     description: This user's presence.
                   last_active_ago:
                     type: integer
@@ -113,26 +112,53 @@ paths:
                       The length of time in milliseconds since an action was performed
                       by this user.
                   status_msg:
-                type: [string, "null"]
                     description: The state message for this user if one was set.
+                    type: ["string", "null"]
                   currently_active:
                     type: boolean
-                description: "Whether the user is currently active"
+                    description: Whether the user is currently active
-            required: ["presence"]
+                required:
-        404:
+                  - presence
-          description: |-
+              examples:
-            There is no presence state for this user. This user may not exist or
+                response:
-            isn't exposing presence information to you.
+                  value: {
-          schema:
+                    "presence": "unavailable",
-            "$ref": "definitions/errors/error.yaml"
+                    "last_active_ago": 420845
-        403:
+                  }
+        "403":
           description: You are not allowed to see this user's presence status.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "You are not allowed to see their presence"
                   }
+        "404":
+          description: |-
+            There is no presence state for this user. This user may not exist or
+            isn't exposing presence information to you.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
       tags:
         - Presence
+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

data/api/client-server/profile.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 Profile API"
+  title: Matrix Client-Server Profile API
-  version: "1.0.0"
+  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
 paths:
   "/profile/{userId}/displayname":
     put:
@@ -38,15 +27,15 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           description: The user whose display name to set.
           required: true
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
-        - in: body
+          schema:
-          name: displayName
+            type: string
-          description: The new display name information.
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               example: {
@@ -56,18 +45,24 @@ paths:
                 displayname:
                   type: string
                   description: The new display name for this user.
+        description: The new display name information.
+        required: true
       responses:
-        200:
+        "200":
           description: The display name was set.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object  # empty json object
-        429:
+              examples:
+                response:
+                  value: {}
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - User data
     get:
@@ -79,25 +74,30 @@ paths:
       operationId: getDisplayName
       parameters:
         - in: path
-          type: string
           name: userId
           description: The user whose display name to get.
           required: true
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The display name for this user.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "displayname": "Alice Margatroid"
-              }
               schema:
                 type: object
                 properties:
                   displayname:
                     type: string
-                description: The user's display name if they have set one, otherwise not present.
+                    description: The user's display name if they have set one, otherwise not
-        404:
+                      present.
+              examples:
+                response:
+                  value: {
+                    "displayname": "Alice Margatroid"
+                  }
+        "404":
           description: There is no display name for this user or this user does not exist.
       tags:
         - User data
@@ -112,15 +112,15 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           description: The user whose avatar URL to set.
           required: true
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
-        - in: body
+          schema:
-          name: avatar_url
+            type: string
-          description: The new avatar information.
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               example: {
@@ -131,18 +131,24 @@ paths:
                   type: string
                   format: uri
                   description: The new avatar URL for this user.
+        description: The new avatar information.
+        required: true
       responses:
-        200:
+        "200":
           description: The avatar URL was set.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object  # empty json object
-        429:
+              examples:
+                response:
+                  value: {}
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - User data
     get:
@@ -154,18 +160,17 @@ paths:
       operationId: getAvatarUrl
       parameters:
         - in: path
-          type: string
           name: userId
           description: The user whose avatar URL to get.
           required: true
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The avatar URL for this user.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "avatar_url": "mxc://matrix.org/SDGdghriugerRg"
-              }
               schema:
                 type: object
                 properties:
@@ -173,7 +178,12 @@ paths:
                     type: string
                     format: uri
                     description: The user's avatar URL if they have set one, otherwise not present.
-        404:
+              examples:
+                response:
+                  value: {
+                    "avatar_url": "mxc://matrix.org/SDGdghriugerRg"
+                  }
+        "404":
           description: There is no avatar URL for this user or this user does not exist.
       tags:
         - User data
@@ -188,19 +198,17 @@ paths:
       operationId: getUserProfile
       parameters:
         - in: path
-          type: string
           name: userId
           description: The user whose profile information to get.
           required: true
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The profile information for this user.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
-                "displayname": "Alice Margatroid"
-              }
               schema:
                 type: object
                 properties:
@@ -210,25 +218,55 @@ paths:
                     description: The user's avatar URL if they have set one, otherwise not present.
                   displayname:
                     type: string
-                description: The user's display name if they have set one, otherwise not present.
+                    description: The user's display name if they have set one, otherwise not
-        403:
+                      present.
+              examples:
+                response:
+                  value: {
+                    "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
+                    "displayname": "Alice Margatroid"
+                  }
+        "403":
           x-addedInMatrixVersion: "1.2"
-          description: The server is unwilling to disclose whether the user exists and/or has profile information.
+          description: The server is unwilling to disclose whether the user exists and/or
+            has profile information.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "Profile lookup over federation is disabled on this homeserver"
                   }
+        "404":
+          description: There is no profile information for this user or this user does not
+            exist.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
-        404:
-          description: There is no profile information for this user or this user does not exist.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Profile not found"
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - User data
+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

data/api/client-server/pusher.yaml

@@ -12,58 +12,30 @@
 # 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 Push API"
+  title: Matrix Client-Server Push API
-  version: "1.0.0"
+  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
 paths:
-  "/pushers":
+  /pushers:
     get:
       summary: Gets the current pushers for the authenticated user
-      description: |-
+      description: Gets all currently active pushers for the authenticated user.
-          Gets all currently active pushers for the authenticated user.
       operationId: getPushers
       security:
         - accessToken: []
       responses:
-        200:
+        "200":
           description: The pushers for this user.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "pushers": [
-                {
-                  "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=",
-                  "kind": "http",
-                  "app_id": "face.mcapp.appy.prod",
-                  "app_display_name": "Appy McAppface",
-                  "device_display_name": "Alice's Phone",
-                  "profile_tag": "xyz",
-                  "lang": "en-US",
-                  "data": {
-                    "url": "https://example.com/_matrix/push/v1/notify"
-                  }
-                }
-              ]
-            }
               schema:
                 type: object
                 properties:
                   pushers:
                     type: array
                     title: Pushers
-                description: |-
+                    description: An array containing the current pushers for the user
-                  An array containing the current pushers for the user
                     items:
                       type: object
                       title: Pusher
@@ -130,9 +102,27 @@ paths:
                         - device_display_name
                         - lang
                         - data
+              examples:
+                response:
+                  value: {
+                    "pushers": [
+                      {
+                        "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=",
+                        "kind": "http",
+                        "app_id": "face.mcapp.appy.prod",
+                        "app_display_name": "Appy McAppface",
+                        "device_display_name": "Alice's Phone",
+                        "profile_tag": "xyz",
+                        "lang": "en-US",
+                        "data": {
+                          "url": "https://example.com/_matrix/push/v1/notify"
+                        }
+                      }
+                    ]
+                  }
       tags:
         - Push notifications
-  "/pushers/set":
+  /pushers/set:
     post:
       summary: Modify a pusher for this user on the homeserver.
       description: |-
@@ -147,11 +137,9 @@ paths:
       operationId: postPusher
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: pusher
+          application/json:
-          description: The pusher information.
-          required: true
             schema:
               type: object
               example: {
@@ -182,13 +170,11 @@ paths:
                     If the `kind` is `"email"`, this is the email address to
                     send notifications to.
                 kind:
-                type:
-                  - "string"
-                  - "null"
                   description: |-
                     The kind of pusher to configure. `"http"` makes a pusher that
                     sends HTTP pokes. `"email"` makes a pusher that emails the
                     user with unread notifications. `null` deletes the pusher.
+                  type: ["string", "null"]
                 app_id:
                   type: string
                   description: |-
@@ -234,7 +220,7 @@ paths:
                         Required if `kind` is `http`. The URL to use to send
                         notifications to. MUST be an HTTPS URL with a path of
                         `/_matrix/push/v1/notify`.
-                    example: "https://push-gateway.location.here/_matrix/push/v1/notify"
+                      example: https://push-gateway.location.here/_matrix/push/v1/notify
                     format:
                       type: string
                       description: |-
@@ -251,27 +237,55 @@ paths:
                     different user IDs. Otherwise, the homeserver must remove any
                     other pushers with the same App ID and pushkey for different
                     users. The default is `false`.
-            required: ['kind', 'app_id', 'pushkey']
+              required:
+                - kind
+                - app_id
+                - pushkey
+        description: The pusher information.
+        required: true
       responses:
-        200:
+        "200":
           description: The pusher was set.
-          examples:
+          content:
-            application/json: {}
+            application/json:
               schema:
                 type: object
                 description: An empty object.
-        400:
+              examples:
+                response:
+                  value: {}
+        "400":
           description: One or more of the pusher values were invalid.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "error": "Missing parameters: lang, data",
                     "errcode": "M_MISSING_PARAM"
                   }
-          schema:
+        "429":
-            "$ref": "definitions/errors/error.yaml"
-        429:
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Push notifications
+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

data/api/client-server/pushrules.yaml

@@ -11,23 +11,12 @@
 # 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 Push Rules API"
+  title: Matrix Client-Server Push Rules API
-  version: "1.0.0"
+  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
 paths:
-  "/pushrules/":
+  /pushrules/:
     get:
       summary: Retrieve all push rulesets.
       description: |-
@@ -39,21 +28,24 @@ paths:
       security:
         - accessToken: []
       responses:
-        200:
+        "200":
           description: All the push rulesets for this user.
+          content:
+            application/json:
               schema:
                 type: object
-            required: ["global"]
+                required:
+                  - global
                 properties:
                   global:
                     type: object
                     description: The global ruleset.
                     title: Ruleset
-                allOf: [
+                    allOf:
-                  "$ref": "definitions/push_ruleset.yaml"
+                      - $ref: definitions/push_ruleset.yaml
-                ]
               examples:
-            application/json: {
+                response:
+                  value: {
                     "global": {
                       "content": [
                         {
@@ -247,113 +239,133 @@ paths:
   "/pushrules/{scope}/{kind}/{ruleId}":
     get:
       summary: Retrieve a push rule.
-      description: |-
+      description: Retrieve a single specified push rule.
-        Retrieve a single specified push rule.
       operationId: getPushRule
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: scope
           required: true
-          x-example: "global"
+          description: "`global` to specify global rules."
-          description: |-
+          example: global
-            `global` to specify global rules.
+          schema:
-        - in: path
             type: string
+        - in: path
           name: kind
           required: true
-          x-example: content
-          enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
-        - in: path
+          example: content
+          schema:
             type: string
+            enum:
+              - override
+              - underride
+              - sender
+              - room
+              - content
+        - in: path
           name: ruleId
           required: true
-          x-example: "nocake"
           description: |
             The identifier for the rule.
+          example: nocake
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: |-
             The specific push rule. This will also include keys specific to the
             rule itself such as the rule's `actions` and `conditions` if set.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: The push rule.
+                allOf:
+                  - $ref: definitions/push_rule.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "actions": [],
                     "pattern": "cake*lie",
                     "rule_id": "nocake",
                     "enabled": true,
                     "default": false
                   }
+        "404":
+          description: The push rule does not exist.
+          content:
+            application/json:
               schema:
-            type: object
+                $ref: definitions/errors/error.yaml
-            description: The push rule.
-            allOf: [
-              "$ref": "definitions/push_rule.yaml"
-            ]
-        404:
-          description: |-
-            The push rule does not exist.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "The push rule was not found."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Push notifications
     delete:
       summary: Delete a push rule.
-      description: |-
+      description: This endpoint removes the push rule defined in the path.
-        This endpoint removes the push rule defined in the path.
       operationId: deletePushRule
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: scope
           required: true
-          x-example: "global"
+          description: "`global` to specify global rules."
-          description: |-
+          example: global
-            `global` to specify global rules.
+          schema:
-        - in: path
             type: string
+        - in: path
           name: kind
           required: true
-          x-example: content
-          enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
-        - in: path
+          example: content
+          schema:
             type: string
+            enum:
+              - override
+              - underride
+              - sender
+              - room
+              - content
+        - in: path
           name: ruleId
           required: true
-          x-example: "nocake"
           description: |
             The identifier for the rule.
+          example: nocake
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The push rule was deleted.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object  # empty json object
-        404:
-          description: |-
-            The push rule does not exist.
               examples:
-            application/json: {
+                response:
+                  value: {}
+        "404":
+          description: The push rule does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "The push rule was not found."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Push notifications
     put:
@@ -380,68 +392,75 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: scope
           required: true
-          x-example: "global"
+          description: "`global` to specify global rules."
-          description: |-
+          example: global
-            `global` to specify global rules.
+          schema:
-        - in: path
             type: string
+        - in: path
           name: kind
           required: true
-          x-example: content
-          enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
-        - in: path
+          example: content
+          schema:
             type: string
+            enum:
+              - override
+              - underride
+              - sender
+              - room
+              - content
+        - in: path
           name: ruleId
           required: true
-          x-example: "nocake"
           description: |
             The identifier for the rule. If the string starts with a dot ("."),
             the request MUST be rejected as this is reserved for server-default
             rules. Slashes ("/") and backslashes ("\\") are also not allowed.
-        - in: query
+          example: nocake
+          schema:
             type: string
+        - in: query
           name: before
           required: false
-          x-example: someRuleId
           description: |-
             Use 'before' with a `rule_id` as its value to make the new rule the
             next-most important rule with respect to the given user defined rule.
             It is not possible to add a rule relative to a predefined server rule.
-        - in: query
+          example: someRuleId
+          schema:
             type: string
+        - in: query
           name: after
           required: false
-          x-example: anotherRuleId
           description: |-
             This makes the new rule the next-less important rule relative to the
             given user defined rule. It is not possible to add a rule relative
             to a predefined server rule.
-        - in: body
+          example: anotherRuleId
-          name: pushrule
+          schema:
-          description: |-
+            type: string
-            The push rule data. Additional top-level keys may be present depending
+      requestBody:
-            on the parameters for the rule `kind`.
+        content:
-          required: true
+          application/json:
             schema:
               type: object
               example: {
                 "pattern": "cake*lie",
-                "actions": ["notify"]
+                "actions": [
+                  "notify"
+                ]
               }
               properties:
                 actions:
                   type: array
-                description: |-
+                  description: The action(s) to perform when the conditions for this rule are met.
-                  The action(s) to perform when the conditions for this rule are met.
                   items:
-                  type:
+                    oneOf:
-                    - string
+                      - type: string
-                    - object
+                      - type: object
                 conditions:
                   type: array
                   description: |-
@@ -450,210 +469,253 @@ paths:
                     always matches. Only applicable to `underride` and `override` rules.
                   items:
                     type: object
-                  allOf: [ "$ref": "definitions/push_condition.yaml" ]
+                    allOf:
+                      - $ref: definitions/push_condition.yaml
                 pattern:
                   type: string
+                  description: Only applicable to `content` rules. The glob-style pattern to match
+                    against.
+              required:
+                - actions
         description: |-
-                  Only applicable to `content` rules. The glob-style pattern to match against.
+          The push rule data. Additional top-level keys may be present depending
-            required: ["actions"]
+          on the parameters for the rule `kind`.
+        required: true
       responses:
-        200:
+        "200":
           description: The push rule was created/updated.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object  # empty json object
-        400:
+              examples:
+                response:
+                  value: {}
+        "400":
           description: There was a problem configuring this push rule.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "error": "before/after rule not found: someRuleId",
                     "errcode": "M_UNKNOWN"
                   }
+        "404":
+          description: The push rule does not exist (when updating a push rule).
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
-        404:
-          description: |-
-            The push rule does not exist (when updating a push rule).
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "The push rule was not found."
                   }
-          schema:
+        "429":
-            "$ref": "definitions/errors/error.yaml"
-        429:
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Push notifications
   "/pushrules/{scope}/{kind}/{ruleId}/enabled":
     get:
-      summary: "Get whether a push rule is enabled"
+      summary: Get whether a push rule is enabled
-      description:
+      description: This endpoint gets whether the specified push rule is enabled.
-        This endpoint gets whether the specified push rule is enabled.
       operationId: isPushRuleEnabled
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: scope
           required: true
-          x-example: "global"
           description: |-
             Either `global` or `device/<profile_tag>` to specify global
             rules or device rules for the given `profile_tag`.
-        - in: path
+          example: global
+          schema:
             type: string
+        - in: path
           name: kind
           required: true
-          x-example: cake
-          enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
-        - in: path
+          example: cake
+          schema:
             type: string
+            enum:
+              - override
+              - underride
+              - sender
+              - room
+              - content
+        - in: path
           name: ruleId
           required: true
-          x-example: nocake
           description: |
             The identifier for the rule.
+          example: nocake
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: Whether the push rule is enabled.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "enabled": true
-              }
               schema:
                 type: object
                 properties:
                   enabled:
                     type: boolean
                     description: Whether the push rule is enabled or not.
-            required: ["enabled"]
+                required:
-        404:
+                  - enabled
-          description: |-
+              examples:
-            The push rule does not exist.
+                response:
+                  value: {
+                    "enabled": true
+                  }
+        "404":
+          description: The push rule does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "The push rule was not found."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Push notifications
     put:
-      summary: "Enable or disable a push rule."
+      summary: Enable or disable a push rule.
-      description: |-
+      description: This endpoint allows clients to enable or disable the specified
-        This endpoint allows clients to enable or disable the specified push rule.
+        push rule.
       operationId: setPushRuleEnabled
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: scope
           required: true
-          x-example: "global"
+          description: "`global` to specify global rules."
-          description: |-
+          example: global
-            `global` to specify global rules.
+          schema:
-        - in: path
             type: string
+        - in: path
           name: kind
           required: true
-          x-example: content
-          enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
-        - in: path
+          example: content
+          schema:
             type: string
+            enum:
+              - override
+              - underride
+              - sender
+              - room
+              - content
+        - in: path
           name: ruleId
           required: true
-          x-example: "nocake"
           description: |
             The identifier for the rule.
-        - in: body
+          example: nocake
-          name: body
+          schema:
-          description: |
+            type: string
-            Whether the push rule is enabled or not.
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               properties:
                 enabled:
                   type: boolean
                   description: Whether the push rule is enabled or not.
-            required: ["enabled"]
+              required:
+                - enabled
               example: {
                 "enabled": true
               }
+        description: |
+          Whether the push rule is enabled or not.
+        required: true
       responses:
-        200:
+        "200":
           description: The push rule was enabled or disabled.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object
-        404:
-          description: |-
-            The push rule does not exist.
               examples:
-            application/json: {
+                response:
+                  value: {}
+        "404":
+          description: The push rule does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "The push rule was not found."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Push notifications
   "/pushrules/{scope}/{kind}/{ruleId}/actions":
     get:
-      summary: "The actions for a push rule"
+      summary: The actions for a push rule
-      description:
+      description: This endpoint get the actions for the specified push rule.
-        This endpoint get the actions for the specified push rule.
       operationId: getPushRuleActions
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: scope
           required: true
-          x-example: "global"
           description: |-
             Either `global` or `device/<profile_tag>` to specify global
             rules or device rules for the given `profile_tag`.
-        - in: path
+          example: global
+          schema:
             type: string
+        - in: path
           name: kind
           required: true
-          x-example: content
-          enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
-        - in: path
+          example: content
+          schema:
             type: string
+            enum:
+              - override
+              - underride
+              - sender
+              - room
+              - content
+        - in: path
           name: ruleId
           required: true
-          x-example: nocake
           description: |
             The identifier for the rule.
+          example: nocake
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The actions for this push rule.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "actions": [
-                  "notify",
-                  {"set_tweak": "sound", "value": "bing"}
-                ]
-              }
               schema:
                 type: object
                 properties:
@@ -661,24 +723,38 @@ paths:
                     type: array
                     description: The action(s) to perform for this rule.
                     items:
-                  type:
+                      oneOf:
-                    - string
+                        - type: string
-                    - object
+                        - type: object
-            required: ["actions"]
+                required:
-        404:
+                  - actions
-          description: |-
-            The push rule does not exist.
               examples:
-            application/json: {
+                response:
+                  value: {
+                    "actions": [
+                      "notify",
+                      {
+                        "set_tweak": "sound",
+                        "value": "bing"
+                      }
+                    ]
+                  }
+        "404":
+          description: The push rule does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "The push rule was not found."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Push notifications
     put:
-      summary: "Set the actions for a push rule."
+      summary: Set the actions for a push rule.
       description: |-
         This endpoint allows clients to change the actions of a push rule.
         This can be used to change the actions of builtin rules.
@@ -687,32 +763,37 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: scope
           required: true
-          x-example: "global"
+          description: "`global` to specify global rules."
-          description: |-
+          example: global
-            `global` to specify global rules.
+          schema:
-        - in: path
             type: string
+        - in: path
           name: kind
           required: true
-          x-example: room
-          enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
-        - in: path
+          example: room
+          schema:
             type: string
+            enum:
+              - override
+              - underride
+              - sender
+              - room
+              - content
+        - in: path
           name: ruleId
           required: true
-          x-example: "#spam:example.com"
           description: |
             The identifier for the rule.
-        - in: body
+          example: "#spam:example.com"
-          name: body
+          schema:
-          description: |
+            type: string
-            The action(s) to perform when the conditions for this rule are met.
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               properties:
@@ -720,33 +801,58 @@ paths:
                   type: array
                   description: The action(s) to perform for this rule.
                   items:
-                  type:
+                    oneOf:
-                    - string
+                      - type: string
-                    - object
+                      - type: object
-            required: ["actions"]
+              required:
+                - actions
               example: {
                 "actions": [
                   "notify",
-                  {"set_tweak": "highlight"}
+                  {
+                    "set_tweak": "highlight"
+                  }
                 ]
               }
+        description: |
+          The action(s) to perform when the conditions for this rule are met.
+        required: true
       responses:
-        200:
+        "200":
           description: The actions for the push rule were set.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object
-        404:
-          description: |-
-            The push rule does not exist.
               examples:
-            application/json: {
+                response:
+                  value: {}
+        "404":
+          description: The push rule does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "The push rule was not found."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Push notifications
+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

data/api/client-server/read_markers.yaml

@@ -12,21 +12,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 Read Marker API"
+  title: Matrix Client-Server Read Marker API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/read_markers":
     post:
@@ -39,52 +28,72 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room ID to set the read marker in for the user.
           required: true
-          x-example: "!somewhere:example.org"
+          example: "!somewhere:example.org"
-        - in: body
+          schema:
-          name: body
+            type: string
-          description: The read marker and optional read receipt locations.
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               properties:
-              "m.fully_read":
+                m.fully_read:
                   type: string
                   description: |-
                     The event ID the read marker should be located at. The
                     event MUST belong to the room.
-                example: "$somewhere:example.org"
+                  example: $somewhere:example.org
                   x-changedInMatrixVersion:
-                  1.4: |
+                    "1.4": |
                       This property is no longer required.
-              "m.read":
+                m.read:
                   type: string
                   description: |-
                     The event ID to set the read receipt location at. This is
                     equivalent to calling `/receipt/m.read/$elsewhere:example.org`
                     and is provided here to save that extra call.
-                example: "$elsewhere:example.org"
+                  example: $elsewhere:example.org
-              "m.read.private":
+                m.read.private:
                   x-addedInMatrixVersion: "1.4"
                   type: string
                   description: |-
                     The event ID to set the *private* read receipt location at. This
                     equivalent to calling `/receipt/m.read.private/$elsewhere:example.org`
                     and is provided here to save that extra call.
-                example: "$elsewhere:example.org"
+                  example: $elsewhere:example.org
+        description: The read marker and optional read receipt locations.
+        required: true
       responses:
-        200:
+        "200":
-          description: |-
+          description: The read marker, and read receipt(s) if provided, have been updated.
-            The read marker, and read receipt(s) if provided, have been updated.
+          content:
+            application/json:
               schema:
                 type: object
                 properties: {}
-        429:
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Read Markers
+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

data/api/client-server/receipts.yaml

@@ -12,21 +12,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 Receipts API"
+  title: Matrix Client-Server Receipts API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/receipt/{receiptType}/{eventId}":
     post:
@@ -39,13 +28,13 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room in which to send the event.
           required: true
-          x-example: "!wefuh21ffskfuh345:example.com"
+          example: "!wefuh21ffskfuh345:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: receiptType
           description: |-
             The type of receipt to send. This can also be `m.fully_read` as an
@@ -55,23 +44,26 @@ paths:
             effectively calls `/read_markers` internally when presented with a receipt
             type of `m.fully_read`.
           required: true
-          x-example: "m.read"
           x-changedInMatrixVersion:
-            1.4: |
+            "1.4": |
               Allow `m.read.private` receipts and `m.fully_read` markers to be set.
-          enum: ["m.read", "m.read.private", "m.fully_read"]
+          example: m.read
-        - in: path
+          schema:
             type: string
+            enum:
+              - m.read
+              - m.read.private
+              - m.fully_read
+        - in: path
           name: eventId
           description: The event ID to acknowledge up to.
           required: true
-          x-example: "$1924376522eioj:example.com"
+          example: $1924376522eioj:example.com
-        - in: body
+          schema:
-          name: receipt
+            type: string
-          description: |-
+      requestBody:
-            Extra receipt information to attach to `content` if any. The
+        content:
-            server will automatically set the `ts` field.
+          application/json:
-          required: true
             schema:
               type: object
               properties:
@@ -86,32 +78,58 @@ paths:
               example: {
                 "thread_id": "main"
               }
+        description: |-
+          Extra receipt information to attach to `content` if any. The
+          server will automatically set the `ts` field.
+        required: true
       responses:
-        200:
+        "200":
           description: The receipt was sent.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object
                 maxProperties: 0  # empty json object
-        429:
+              examples:
-          description: This request was rate-limited.
+                response:
-          schema:
+                  value: {}
-            "$ref": "definitions/errors/rate_limited.yaml"
+        "400":
-        400:
           description: |-
             The `thread_id` is invalid in some way. For example:
             * It is not a string.
             * It is empty.
             * It is provided for an incompatible receipt type.
             * The `event_id` is not related to the `thread_id`.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_INVALID_PARAM",
                     "error": "thread_id field must be a non-empty string"
                   }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Room participation
+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

data/api/client-server/redaction.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 message redaction API"
+  title: Matrix Client-Server message redaction API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/redact/{eventId}/{txnId}":
     put:
@@ -47,28 +36,31 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room from which to redact the event.
           required: true
-          x-example: "!637q39766251:example.com"
+          example: "!637q39766251:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: eventId
           description: The ID of the event to redact
           required: true
-          x-example: "bai2b1i9:matrix.org"
+          example: bai2b1i9:matrix.org
+          schema:
+            type: string
         - in: path
           name: txnId
-          type: string
           description: |-
             The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate a
             unique ID; it will be used by the server to ensure idempotency of requests.
           required: true
-          x-example: "37"
+          example: "37"
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               example: {
@@ -78,19 +70,37 @@ paths:
                 reason:
                   type: string
                   description: The reason for the event being redacted.
+        required: true
       responses:
-        200:
+        "200":
-          description: "An ID for the redaction event."
+          description: An ID for the redaction event.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                  "event_id": "$YUwQidLecu:example.com"
-              }
               schema:
                 type: object
                 properties:
                   event_id:
                     type: string
-                description: |-
+                    description: A unique identifier for the event.
-                  A unique identifier for the event.
+              examples:
+                response:
+                  value: {
+                    "event_id": "$YUwQidLecu:example.com"
+                  }
       tags:
         - Room participation
+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

data/api/client-server/refresh.yaml

@@ -11,21 +11,12 @@
 # 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 Registration and Login API"
+  title: Matrix Client-Server Registration and Login API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v3
-consumes:
-  - application/json
-produces:
-  - application/json
 paths:
-  "/refresh":
+  /refresh:
     post:
       x-addedInMatrixVersion: "1.3"
       summary: Refresh an access token
@@ -48,10 +39,9 @@ paths:
 
         Application Service identity assertion is disabled for this endpoint.
       operationId: refresh
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
               type: object
               example: {
@@ -63,22 +53,18 @@ paths:
                   description: The refresh token
               required:
                 - refresh_token
+        required: true
       responses:
-        200:
+        "200":
           description: A new access token and refresh token were generated.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "access_token": "a_new_token",
-                "expires_in_ms": 60000,
-                "refresh_token": "another_new_token"
-              }
               schema:
                 type: object
                 properties:
                   access_token:
                     type: string
-                description: |-
+                    description: The new access token to use.
-                  The new access token to use.
                   refresh_token:
                     type: string
                     description: |-
@@ -93,18 +79,41 @@ paths:
                       expire.
                 required:
                   - access_token
-        401:
-          description: |-
-            The provided token was unknown, or has already been used.
               examples:
-            application/json: {
+                response:
+                  value: {
+                    "access_token": "a_new_token",
+                    "expires_in_ms": 60000,
+                    "refresh_token": "another_new_token"
+                  }
+        "401":
+          description: The provided token was unknown, or has already been used.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
                     "errcode": "M_UNKNOWN_TOKEN",
                     "error": "Soft logged out",
                     "soft_logout": true
                   }
-          schema:
+        "429":
-            "$ref": "definitions/errors/error.yaml"
-        429:
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3

data/api/client-server/registration.yaml

@@ -12,21 +12,12 @@
 # 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 Registration API"
+  title: Matrix Client-Server Registration API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v3
-consumes:
-  - application/json
-produces:
-  - application/json
 paths:
-  "/register":
+  /register:
     post:
       summary: Register for an account on this homeserver.
       description: |-
@@ -73,19 +64,20 @@ paths:
       parameters:
         - in: query
           name: kind
-          type: string
+          required: false
+          description: The kind of account to register. Defaults to `user`.
           # swagger-UI overrides the default with the example, so better make the
           # example the default.
-          x-example: user
+          example: user
-          required: false
+          schema:
-          default: user
+            type: string
             enum:
               - guest
               - user
-          description: The kind of account to register. Defaults to `user`.
+            default: user
-        - in: body
+      requestBody:
-          name: body
+        content:
-          required: true
+          application/json:
             schema:
               type: object
               properties:
@@ -97,7 +89,7 @@ paths:
                     should be authenticated, but is instead used to
                     authenticate the `register` call itself.
                   allOf:
-                - "$ref": "definitions/auth_data.yaml"
+                    - $ref: definitions/auth_data.yaml
                 username:
                   type: string
                   description: |-
@@ -130,18 +122,14 @@ paths:
                   example: false
                 refresh_token:
                   type: boolean
-                description: |-
+                  description: If true, the client supports refresh tokens.
-                  If true, the client supports refresh tokens.
                   x-addedInMatrixVersion: "1.3"
+        required: true
       responses:
-        200:
+        "200":
           description: The account has been registered.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "user_id": "@cheeky_monkey:matrix.org",
-                "access_token": "abc123",
-                "device_id": "GHTYAJCE"
-              }
               schema:
                 type: object
                 properties:
@@ -194,8 +182,16 @@ paths:
                       ID of the registered device. Will be the same as the
                       corresponding parameter in the request, if one was specified.
                       Required if the `inhibit_login` option is false.
-            required: ['user_id']
+                required:
-        400:
+                  - user_id
+              examples:
+                response:
+                  value: {
+                    "user_id": "@cheeky_monkey:matrix.org",
+                    "access_token": "abc123",
+                    "device_id": "GHTYAJCE"
+                  }
+        "400":
           description: |-
             Part of the request was invalid. This may include one of the following error codes:
 
@@ -212,69 +208,72 @@ paths:
             performing User-Interactive Authentication, although they may also return
             them after authentication is completed if, for example, the requested user ID
             was registered whilst the client was performing authentication.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_USER_IN_USE",
                     "error": "Desired user ID is already taken."
                   }
+        "401":
+          description: The homeserver requires additional authentication information.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/auth_response.yaml
-        401:
+        "403":
-          description: |-
-            The homeserver requires additional authentication information.
-          schema:
-            "$ref": "definitions/auth_response.yaml"
-        403:
           description: |-
             The homeserver does not permit registering the account. This response
             can be used to identify that a particular `kind` of account is not
             allowed, or that registration is generally not supported by the homeserver.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "Registration is disabled"
                   }
-          schema:
+        "429":
-            "$ref": "definitions/errors/error.yaml"
-        429:
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Account management
-  "/register/email/requestToken":
+  /register/email/requestToken:
     post:
-      summary: Begins the validation process for an email to be used during registration.
+      summary: Begins the validation process for an email to be used during
+        registration.
       description: |-
         The homeserver must check that the given email address is **not**
         already associated with an account on this homeserver. The homeserver
         should validate the email itself, either by sending a validation email
         itself or by using a service it has control over.
       operationId: requestTokenToRegisterEmail
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
-            $ref: "definitions/request_email_validation.yaml"
+              $ref: definitions/request_email_validation.yaml
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             An email has been sent to the specified address. Note that this
             may be an email containing the validation token or it may be
             informing the user of an error.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/request_token_response.yaml"
+                $ref: definitions/request_token_response.yaml
-        403:
+        "400":
-          description: The homeserver does not permit the address to be bound.
-          schema:
-            $ref: "definitions/errors/error.yaml"
-          examples:
-            application/json: {
-              "errcode": "M_THREEPID_DENIED",
-              "error": "Third-party identifier is not allowed"
-            }
-        400:
           description: |-
             Part of the request was invalid. This may include one of the following error codes:
 
@@ -285,48 +284,57 @@ paths:
               has an account on the homeserver in question.
             * `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server
               that is not trusted by this homeserver.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_THREEPID_IN_USE",
                     "error": "The specified address is already in use"
                   }
+        "403":
+          description: The homeserver does not permit the address to be bound.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_DENIED",
+                    "error": "Third-party identifier is not allowed"
+                  }
       tags:
         - Account management
-  "/register/msisdn/requestToken":
+  /register/msisdn/requestToken:
     post:
-      summary: Requests a validation token be sent to the given phone number for the purpose of registering an account
+      summary: Requests a validation token be sent to the given phone number for the
+        purpose of registering an account
       description: |-
         The homeserver must check that the given phone number is **not**
         already associated with an account on this homeserver. The homeserver
         should validate the phone number itself, either by sending a validation
         message itself or by using a service it has control over.
       operationId: requestTokenToRegisterMSISDN
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
-            $ref: "definitions/request_msisdn_validation.yaml"
+              $ref: definitions/request_msisdn_validation.yaml
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             An SMS message has been sent to the specified phone number. Note
             that this may be an SMS message containing the validation token or
             it may be informing the user of an error.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/request_token_response.yaml"
+                $ref: definitions/request_token_response.yaml
-        403:
+        "400":
-          description: The homeserver does not permit the address to be bound.
-          schema:
-            $ref: "definitions/errors/error.yaml"
-          examples:
-            application/json: {
-              "errcode": "M_THREEPID_DENIED",
-              "error": "Third-party identifier is not allowed"
-            }
-        400:
           description: |-
             Part of the request was invalid. This may include one of the following error codes:
 
@@ -337,18 +345,33 @@ paths:
               has an account on the homeserver in question.
             * `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server
               that is not trusted by this homeserver.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_THREEPID_IN_USE",
                     "error": "The specified address is already in use"
                   }
+        "403":
+          description: The homeserver does not permit the address to be bound.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_DENIED",
+                    "error": "Third-party identifier is not allowed"
+                  }
       tags:
         - Account management
-  "/account/password":
+  /account/password:
     post:
-      summary: "Changes a user's password."
+      summary: Changes a user's password.
       description: |-
         Changes the password for an account on this homeserver.
 
@@ -366,17 +389,16 @@ paths:
       security:
         - accessToken: []
       operationId: changePassword
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
               type: object
               properties:
                 new_password:
                   type: string
                   description: The new password for the account.
-                example: "ihatebananas"
+                  example: ihatebananas
                 logout_devices:
                   type: boolean
                   description: |-
@@ -387,32 +409,41 @@ paths:
                     for the user's remaining devices.
                   example: true
                 auth:
-                description: |-
+                  description: Additional authentication information for the user-interactive
-                    Additional authentication information for the user-interactive authentication API.
+                    authentication API.
                   allOf:
-                - "$ref": "definitions/auth_data.yaml"
+                    - $ref: definitions/auth_data.yaml
-            required: ["new_password"]
+              required:
+                - new_password
+        required: true
       responses:
-        200:
+        "200":
           description: The password has been changed.
-          examples:
+          content:
-            application/json: {}
+            application/json:
               schema:
                 type: object
-        401:
+              examples:
-          description: |-
+                response:
-            The homeserver requires additional authentication information.
+                  value: {}
-          schema:
+        "401":
-            "$ref": "definitions/auth_response.yaml"
+          description: The homeserver requires additional authentication information.
-        429:
+          content:
+            application/json:
+              schema:
+                $ref: definitions/auth_response.yaml
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Account management
-  "/account/password/email/requestToken":
+  /account/password/email/requestToken:
     post:
-      summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password
+      summary: Requests a validation token be sent to the given email address for the
+        purpose of resetting a user's password
       description: |-
         The homeserver must check that the given email address **is
         associated** with an account on this homeserver. This API should be
@@ -430,46 +461,55 @@ paths:
         The homeserver should validate the email itself, either by sending a
         validation email itself or by using a service it has control over.
       operationId: requestTokenToResetPasswordEmail
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
-            $ref: "definitions/request_email_validation.yaml"
+              $ref: definitions/request_email_validation.yaml
+        required: true
       responses:
-        200:
+        "200":
           description: An email was sent to the given address.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/request_token_response.yaml"
+                $ref: definitions/request_token_response.yaml
-        403:
+        "400":
-          description: |-
-            The homeserver does not allow the third-party identifier as a
-            contact option.
-          schema:
-            $ref: "definitions/errors/error.yaml"
-          examples:
-            application/json: {
-              "errcode": "M_THREEPID_DENIED",
-              "error": "Third-party identifier is not allowed"
-            }
-        400:
           description: |-
             The referenced third-party identifier is not recognised by the
             homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
             can be returned if the server does not trust/support the identity server
             provided in the request.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_THREEPID_NOT_FOUND",
                     "error": "Email not found"
                   }
+        "403":
+          description: |-
+            The homeserver does not allow the third-party identifier as a
+            contact option.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_DENIED",
+                    "error": "Third-party identifier is not allowed"
+                  }
       tags:
         - Account management
-  "/account/password/msisdn/requestToken":
+  /account/password/msisdn/requestToken:
     post:
-      summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.
+      summary: Requests a validation token be sent to the given phone number for the
+        purpose of resetting a user's password.
       description: |-
         The homeserver must check that the given phone number **is
         associated** with an account on this homeserver. This API should be
@@ -487,46 +527,54 @@ paths:
         The homeserver should validate the phone number itself, either by sending a
         validation message itself or by using a service it has control over.
       operationId: requestTokenToResetPasswordMSISDN
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
-            $ref: "definitions/request_msisdn_validation.yaml"
+              $ref: definitions/request_msisdn_validation.yaml
+        required: true
       responses:
-        200:
+        "200":
           description: An SMS message was sent to the given phone number.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/request_token_response.yaml"
+                $ref: definitions/request_token_response.yaml
-        403:
+        "400":
-          description: |-
-            The homeserver does not allow the third-party identifier as a
-            contact option.
-          schema:
-            $ref: "definitions/errors/error.yaml"
-          examples:
-            application/json: {
-              "errcode": "M_THREEPID_DENIED",
-              "error": "Third-party identifier is not allowed"
-            }
-        400:
           description: |-
             The referenced third-party identifier is not recognised by the
             homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`
             can be returned if the server does not trust/support the identity server
             provided in the request.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_THREEPID_NOT_FOUND",
                     "error": "Phone number not found"
                   }
+        "403":
+          description: |-
+            The homeserver does not allow the third-party identifier as a
+            contact option.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_THREEPID_DENIED",
+                    "error": "Third-party identifier is not allowed"
+                  }
       tags:
         - Account management
-  "/account/deactivate":
+  /account/deactivate:
     post:
-      summary: "Deactivate a user's account."
+      summary: Deactivate a user's account.
       description: |-
         Deactivate the user's account, removing all ability for the user to
         login again.
@@ -545,18 +593,17 @@ paths:
       security:
         - accessToken: []
       operationId: deactivateAccount
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
               type: object
               properties:
                 auth:
-                description: |-
+                  description: Additional authentication information for the user-interactive
-                  Additional authentication information for the user-interactive authentication API.
+                    authentication API.
                   allOf:
-                  - $ref: "definitions/auth_data.yaml"
+                    - $ref: definitions/auth_data.yaml
                 id_server:
                   type: string
                   description: |-
@@ -566,18 +613,21 @@ paths:
                     homeserver does not know which `id_server` that was,
                     it must return an `id_server_unbind_result` of
                     `no-support`.
-                example: "example.org"
+                  example: example.org
+        required: true
       responses:
-        200:
+        "200":
           description: The account has been deactivated.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
                   id_server_unbind_result:
                     type: string
                     enum:
-                  - "success"
+                      - success
-                  - "no-support"
+                      - no-support
                     description: |-
                       An indicator as to whether or not the homeserver was able to unbind
                       the user's 3PIDs from the identity server(s). `success` indicates
@@ -587,21 +637,24 @@ paths:
                       being unable to determine an identity server to unbind from. This
                       must be `success` if the homeserver has no identifiers to unbind
                       for the user.
-                example: "success"
+                    example: success
                 required:
                   - id_server_unbind_result
-        401:
+        "401":
-          description: |-
+          description: The homeserver requires additional authentication information.
-            The homeserver requires additional authentication information.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/auth_response.yaml"
+                $ref: definitions/auth_response.yaml
-        429:
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Account management
-  "/register/available":
+  /register/available:
     get:
       summary: Checks to see if a username is available on the server.
       description: |-
@@ -621,18 +674,17 @@ paths:
       parameters:
         - in: query
           name: username
-          type: string
-          x-example: my_cool_localpart
           required: true
-          default: my_cool_localpart
           description: The username to check the availability of.
+          example: my_cool_localpart
+          schema:
+            type: string
+            default: my_cool_localpart
       responses:
-        200:
+        "200":
           description: The username is available
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "available": true
-            }
               schema:
                 type: object
                 properties:
@@ -641,7 +693,12 @@ paths:
                     description: |-
                       A flag to indicate that the username is available. This should always
                       be `true` when the server replies with 200 OK.
-        400:
+              examples:
+                response:
+                  value: {
+                    "available": true
+                  }
+        "400":
           description: |-
             Part of the request was invalid or the username is not available. This may
             include one of the following error codes:
@@ -650,16 +707,33 @@ paths:
             * `M_INVALID_USERNAME` : The desired username is not a valid user name.
             * `M_EXCLUSIVE` : The desired username is in the exclusive namespace
               claimed by an application service.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_USER_IN_USE",
                     "error": "Desired user ID is already taken."
                   }
-          schema:
+        "429":
-            "$ref": "definitions/errors/error.yaml"
-        429:
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Account management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3

data/api/client-server/registration_tokens.yaml

@@ -11,21 +11,12 @@
 # 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 Registration Token API"
+  title: Matrix Client-Server Registration Token API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v1
-consumes:
-  - application/json
-produces:
-  - application/json
 paths:
-  "/register/m.login.registration_token/validity":
+  /register/m.login.registration_token/validity:
     get:
       x-addedInMatrixVersion: "1.2"
       summary: Query if a given registration token is still valid.
@@ -40,17 +31,16 @@ paths:
       parameters:
         - in: query
           name: token
-          type: string
-          x-example: "fBVFdqVE"
           required: true
           description: The token to check validity of.
+          example: fBVFdqVE
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The check has a result.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "valid": true
-            }
               schema:
                 type: object
                 properties:
@@ -60,21 +50,44 @@ paths:
                       True if the token is still valid, false otherwise. This should
                       additionally be false if the token is not a recognised token by
                       the server.
-            required: ['valid']
+                required:
-        403:
+                  - valid
+              examples:
+                response:
+                  value: {
+                    "valid": true
+                  }
+        "403":
           description: |-
             The homeserver does not permit registration and thus all tokens are
             considered invalid.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "Registration is not enabled on this homeserver."
                   }
-          schema:
+        "429":
-            "$ref": "definitions/errors/error.yaml"
-        429:
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Account management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1

data/api/client-server/relations.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 Relations API"
+  title: Matrix Client-Server Relations API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/rooms/{roomId}/relations/{eventId}":
     get:
@@ -45,19 +34,20 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The ID of the room containing the parent event.
           required: true
-          x-example: "!636q39766251:matrix.org"
+          example: "!636q39766251:matrix.org"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: eventId
           description: The ID of the parent event whose child events are to be returned.
           required: true
-          x-example: "$asfDuShaf7Gafaw"
+          example: $asfDuShaf7Gafaw
-        - in: query
+          schema:
             type: string
+        - in: query
           name: from
           description: |-
             The pagination token to start returning results from. If not supplied, results
@@ -67,9 +57,10 @@ paths:
             `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
             or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
           required: false
-          x-example: "page2_token"
+          example: page2_token
-        - in: query
+          schema:
             type: string
+        - in: query
           name: to
           description: |-
             The pagination token to stop returning results at. If not supplied, results
@@ -78,9 +69,10 @@ paths:
             Like `from`, this can be a previous token from a prior call to this endpoint
             or from `/messages` or `/sync`.
           required: false
-          x-example: "page3_token"
+          example: page3_token
+          schema:
+            type: string
         - in: query
-          type: integer
           name: limit
           description: |-
             The maximum number of results to return in a single `chunk`. The server can
@@ -88,10 +80,10 @@ paths:
 
             Similarly, the server should apply a default value when not supplied.
           required: false
-          x-example: 20
+          example: 20
+          schema:
+            type: integer
         - in: query
-          type: string
-          enum: ["b", "f"]
           name: dir
           x-addedInMatrixVersion: "1.4"
           description: |-
@@ -99,41 +91,32 @@ paths:
             will be returned in chronological order starting at `from`. If it
             is set to `b`, events will be returned in *reverse* chronological
             order, again starting at `from`.
+          schema:
+            type: string
+            enum:
+              - b
+              - f
       responses:
         # note: this endpoint deliberately does not support rate limiting, therefore a
         # 429 error response is not included.
-
+        "200":
-        200:
           description: |-
             The paginated child events which point to the parent. If no events are
             pointing to the parent or the pagination yields no results, an empty `chunk`
             is returned.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "chunk": [{
-                "room_id": "!636q39766251:matrix.org",
-                "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
-                "content": {
-                  "m.relates_to": {
-                    "rel_type": "org.example.my_relation",
-                    "event_id": "$asfDuShaf7Gafaw"
-                  }
-                }
-              }],
-              "next_batch": "page2_token",
-              "prev_batch": "page1_token"
-            }
               schema:
                 type: object
                 properties:
                   chunk:
-                title: "ChildEventsChunk"
+                    title: ChildEventsChunk
                     type: array
-                description: |-
+                    description: The child events of the requested event, ordered topologically
-                  The child events of the requested event, ordered topologically most-recent first.
+                      most-recent first.
                     items:
                       allOf:
-                    - "$ref": "definitions/client_event.yaml"
+                        - $ref: definitions/client_event.yaml
                   next_batch:
                     type: string
                     description: |-
@@ -144,18 +127,40 @@ paths:
                     description: |-
                       An opaque string representing a pagination token. The absence of this token
                       means this is the start of the result set, i.e. this is the first batch/page.
-            required: ['chunk']
+                required:
-        404:
+                  - chunk
+              examples:
+                response:
+                  value: {
+                    "chunk": [
+                      {
+                        "room_id": "!636q39766251:matrix.org",
+                        "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
+                        "content": {
+                          "m.relates_to": {
+                            "rel_type": "org.example.my_relation",
+                            "event_id": "$asfDuShaf7Gafaw"
+                          }
+                        }
+                      }
+                    ],
+                    "next_batch": "page2_token",
+                    "prev_batch": "page1_token"
+                  }
+        "404":
           description: |-
             The parent event was not found or the user does not have permission to read
             this event (it might be contained in history that is not accessible to the user).
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Event not found."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Event relationships
   # The same as above, with added `/{relType}`
@@ -178,26 +183,28 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The ID of the room containing the parent event.
           required: true
-          x-example: "!636q39766251:matrix.org"
+          example: "!636q39766251:matrix.org"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: eventId
           description: The ID of the parent event whose child events are to be returned.
           required: true
-          x-example: "$asfDuShaf7Gafaw"
+          example: $asfDuShaf7Gafaw
-        - in: path
+          schema:
             type: string
+        - in: path
           name: relType
-          description: |-
+          description: The [relationship type](/client-server-api/#relationship-types) to
-            The [relationship type](/client-server-api/#relationship-types) to search for.
+            search for.
           required: true
-          x-example: "org.example.my_relation"
+          example: org.example.my_relation
-        - in: query
+          schema:
             type: string
+        - in: query
           name: from
           description: |-
             The pagination token to start returning results from. If not supplied, results
@@ -207,9 +214,10 @@ paths:
             `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
             or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
           required: false
-          x-example: "page2_token"
+          example: page2_token
-        - in: query
+          schema:
             type: string
+        - in: query
           name: to
           description: |-
             The pagination token to stop returning results at. If not supplied, results
@@ -218,9 +226,10 @@ paths:
             Like `from`, this can be a previous token from a prior call to this endpoint
             or from `/messages` or `/sync`.
           required: false
-          x-example: "page3_token"
+          example: page3_token
+          schema:
+            type: string
         - in: query
-          type: integer
           name: limit
           description: |-
             The maximum number of results to return in a single `chunk`. The server can
@@ -228,10 +237,10 @@ paths:
 
             Similarly, the server should apply a default value when not supplied.
           required: false
-          x-example: 20
+          example: 20
+          schema:
+            type: integer
         - in: query
-          type: string
-          enum: ["b", "f"]
           name: dir
           x-addedInMatrixVersion: "1.4"
           description: |-
@@ -239,35 +248,26 @@ paths:
             will be returned in chronological order starting at `from`. If it
             is set to `b`, events will be returned in *reverse* chronological
             order, again starting at `from`.
+          schema:
+            type: string
+            enum:
+              - b
+              - f
       responses:
         # note: this endpoint deliberately does not support rate limiting, therefore a
         # 429 error response is not included.
-
+        "200":
-        200:
           description: |-
             The paginated child events which point to the parent. If no events are
             pointing to the parent or the pagination yields no results, an empty `chunk`
             is returned.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "chunk": [{
-                "room_id": "!636q39766251:matrix.org",
-                "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
-                "content": {
-                  "m.relates_to": {
-                    "rel_type": "org.example.my_relation",
-                    "event_id": "$asfDuShaf7Gafaw"
-                  }
-                }
-              }],
-              "next_batch": "page2_token",
-              "prev_batch": "page1_token"
-            }
               schema:
                 type: object
                 properties:
                   chunk:
-                title: "ChildEventsChunk"
+                    title: ChildEventsChunk
                     type: array
                     description: |-
                       The child events of the requested event, ordered topologically
@@ -275,7 +275,7 @@ paths:
                       supplied in the URL.
                     items:
                       allOf:
-                    - "$ref": "definitions/client_event.yaml"
+                        - $ref: definitions/client_event.yaml
                   next_batch:
                     type: string
                     description: |-
@@ -286,24 +286,47 @@ paths:
                     description: |-
                       An opaque string representing a pagination token. The absence of this token
                       means this is the start of the result set, i.e. this is the first batch/page.
-            required: ['chunk']
+                required:
-        404:
+                  - chunk
+              examples:
+                response:
+                  value: {
+                    "chunk": [
+                      {
+                        "room_id": "!636q39766251:matrix.org",
+                        "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
+                        "content": {
+                          "m.relates_to": {
+                            "rel_type": "org.example.my_relation",
+                            "event_id": "$asfDuShaf7Gafaw"
+                          }
+                        }
+                      }
+                    ],
+                    "next_batch": "page2_token",
+                    "prev_batch": "page1_token"
+                  }
+        "404":
           description: |-
             The parent event was not found or the user does not have permission to read
             this event (it might be contained in history that is not accessible to the user).
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Event not found."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Event relationships
   # The same as above, with added `/{eventType}`
   "/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}":
     get:
-      summary: Get the child events for a given parent event, with a given `relType` and `eventType`.
+      summary: Get the child events for a given parent event, with a given `relType`
+        and `eventType`.
       description: |-
         Retrieve all of the child events for a given parent event which relate to the parent
         using the given `relType` and have the given `eventType`.
@@ -320,26 +343,28 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The ID of the room containing the parent event.
           required: true
-          x-example: "!636q39766251:matrix.org"
+          example: "!636q39766251:matrix.org"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: eventId
           description: The ID of the parent event whose child events are to be returned.
           required: true
-          x-example: "$asfDuShaf7Gafaw"
+          example: $asfDuShaf7Gafaw
-        - in: path
+          schema:
             type: string
+        - in: path
           name: relType
-          description: |-
+          description: The [relationship type](/client-server-api/#relationship-types) to
-            The [relationship type](/client-server-api/#relationship-types) to search for.
+            search for.
           required: true
-          x-example: "org.example.my_relation"
+          example: org.example.my_relation
-        - in: path
+          schema:
             type: string
+        - in: path
           name: eventType
           description: |-
             The event type of child events to search for.
@@ -347,9 +372,10 @@ paths:
             Note that in encrypted rooms this will typically always be `m.room.encrypted`
             regardless of the event type contained within the encrypted payload.
           required: true
-          x-example: "m.room.message"
+          example: m.room.message
-        - in: query
+          schema:
             type: string
+        - in: query
           name: from
           description: |-
             The pagination token to start returning results from. If not supplied, results
@@ -359,9 +385,10 @@ paths:
             `start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
             or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
           required: false
-          x-example: "page2_token"
+          example: page2_token
-        - in: query
+          schema:
             type: string
+        - in: query
           name: to
           description: |-
             The pagination token to stop returning results at. If not supplied, results
@@ -370,9 +397,10 @@ paths:
             Like `from`, this can be a previous token from a prior call to this endpoint
             or from `/messages` or `/sync`.
           required: false
-          x-example: "page3_token"
+          example: page3_token
+          schema:
+            type: string
         - in: query
-          type: integer
           name: limit
           description: |-
             The maximum number of results to return in a single `chunk`. The server can
@@ -380,10 +408,10 @@ paths:
 
             Similarly, the server should apply a default value when not supplied.
           required: false
-          x-example: 20
+          example: 20
+          schema:
+            type: integer
         - in: query
-          type: string
-          enum: ["b", "f"]
           name: dir
           x-addedInMatrixVersion: "1.4"
           description: |-
@@ -391,35 +419,26 @@ paths:
             will be returned in chronological order starting at `from`. If it
             is set to `b`, events will be returned in *reverse* chronological
             order, again starting at `from`.
+          schema:
+            type: string
+            enum:
+              - b
+              - f
       responses:
         # note: this endpoint deliberately does not support rate limiting, therefore a
         # 429 error response is not included.
-
+        "200":
-        200:
           description: |-
             The paginated child events which point to the parent. If no events are
             pointing to the parent or the pagination yields no results, an empty `chunk`
             is returned.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "chunk": [{
-                "room_id": "!636q39766251:matrix.org",
-                "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
-                "content": {
-                  "m.relates_to": {
-                    "rel_type": "org.example.my_relation",
-                    "event_id": "$asfDuShaf7Gafaw"
-                  }
-                }
-              }],
-              "next_batch": "page2_token",
-              "prev_batch": "page1_token"
-            }
               schema:
                 type: object
                 properties:
                   chunk:
-                title: "ChildEventsChunk"
+                    title: ChildEventsChunk
                     type: array
                     description: |-
                       The child events of the requested event, ordered topologically most-recent
@@ -427,7 +446,7 @@ paths:
                       in the URL.
                     items:
                       allOf:
-                    - "$ref": "definitions/client_event.yaml"
+                        - $ref: definitions/client_event.yaml
                   next_batch:
                     type: string
                     description: |-
@@ -438,18 +457,54 @@ paths:
                     description: |-
                       An opaque string representing a pagination token. The absence of this token
                       means this is the start of the result set, i.e. this is the first batch/page.
-            required: ['chunk']
+                required:
-        404:
+                  - chunk
+              examples:
+                response:
+                  value: {
+                    "chunk": [
+                      {
+                        "room_id": "!636q39766251:matrix.org",
+                        "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
+                        "content": {
+                          "m.relates_to": {
+                            "rel_type": "org.example.my_relation",
+                            "event_id": "$asfDuShaf7Gafaw"
+                          }
+                        }
+                      }
+                    ],
+                    "next_batch": "page2_token",
+                    "prev_batch": "page1_token"
+                  }
+        "404":
           description: |-
             The parent event was not found or the user does not have permission to read
             this event (it might be contained in history that is not accessible to the user).
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Event not found."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Event relationships
-
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/client-server/report_content.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 Report Content API"
+  title: Matrix Client-Server Report Content API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/report/{eventId}":
     post:
@@ -36,20 +25,22 @@ paths:
       operationId: reportContent
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room in which the event being reported is located.
           required: true
-          x-example: "!637q39766251:example.com"
+          example: "!637q39766251:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: eventId
           description: The event to report.
           required: true
-          x-example: "$something:example.org"
+          example: $something:example.org
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               example: {
@@ -65,14 +56,33 @@ paths:
                 reason:
                   type: string
                   description: The reason the content is being reported. May be blank.
+        required: true
       security:
         - accessToken: []
       responses:
-        200:
+        "200":
           description: The event has been reported successfully.
+          content:
+            application/json:
               schema:
                 type: object
               examples:
-            application/json: {}
+                response:
+                  value: {}
       tags:
         - Reporting content
+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

data/api/client-server/room_event_by_timestamp.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 events in room by date API"
+  title: Matrix Client-Server events in room by date API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/rooms/{roomId}/timestamp_to_event":
     get:
@@ -60,38 +49,43 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The ID of the room to search
           required: true
-          x-example: "!636q39766251:matrix.org"
+          example: "!636q39766251:matrix.org"
+          schema:
+            type: string
         - in: query
-          type: integer
           name: ts
           description: |-
             The timestamp to search from, as given in milliseconds
             since the Unix epoch.
           required: true
-          x-example: 1432684800000
+          example: 1432684800000
+          schema:
+            type: integer
         - in: query
-          type: string
-          enum: [f, b]
           name: dir
-          description: |-
+          description: The direction in which to search.  `f` for forwards, `b` for
-            The direction in which to search.  `f` for forwards, `b` for backwards.
+            backwards.
           required: true
-          x-example: f
+          example: f
+          schema:
+            type: string
+            enum:
+              - f
+              - b
       responses:
-        200:
+        "200":
-          description: |-
+          description: An event was found matching the search parameters.
-            An event was found matching the search parameters.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
                   event_id:
                     type: string
-                description: |-
+                    description: The ID of the event found
-                  The ID of the event found
                   origin_server_ts:
                     type: integer
                     description: |-
@@ -99,25 +93,47 @@ paths:
                       This makes it easy to do a quick comparison to see if the
                       `event_id` fetched is too far out of range to be useful for your
                       use case.
-            required: ['event_id', 'origin_server_ts']
+                required:
+                  - event_id
+                  - origin_server_ts
               examples:
-            application/json: {
+                response:
+                  value: {
                     "event_id": "$143273582443PhrSn:example.org",
                     "origin_server_ts": 1432735824653
                   }
-        404:
+        "404":
-          description: |-
+          description: No event was found.
-            No event was found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Unable to find event from 1432684800000 in forward direction"
                   }
-          schema:
+        "429":
-            "$ref": "definitions/errors/error.yaml"
-        429:
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Room participation
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/client-server/room_initial_sync.yaml

@@ -1,18 +1,7 @@
-swagger: '2.0'
+openapi: 3.1.0
 info:
-  title: "Matrix Client-Server Rooms API"
+  title: Matrix Client-Server Rooms API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/initialSync":
     get:
@@ -29,71 +18,36 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room to get the data.
           required: true
-          x-example: "!636q39766251:example.com"
+          example: "!636q39766251:example.com"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The current state of the room
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "membership": "join",
-                "messages": {
-                  "chunk": [
-                    {
-                      "room_id": "!636q39766251:example.com",
-                      "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
-                    },
-                    {
-                      "room_id": "!636q39766251:example.com",
-                      "$ref": "../../event-schemas/examples/m.room.message$m.file.yaml"
-                    }
-                  ],
-                  "end": "s3456_9_0",
-                  "start": "t44-3453_9_0"
-                },
-                "room_id": "!636q39766251:example.com",
-                "state": [
-                  {
-                    "room_id": "!636q39766251:example.com",
-                    "$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
-                  },
-                  {
-                    "room_id": "!636q39766251:example.com",
-                    "$ref": "../../event-schemas/examples/m.room.member.yaml"
-                  },
-                  {
-                    "room_id": "!636q39766251:example.com",
-                    "$ref": "../../event-schemas/examples/m.room.create.yaml"
-                  },
-                  {
-                    "room_id": "!636q39766251:example.com",
-                    "$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
-                  }
-                ],
-                "visibility": "private",
-                "account_data": [{
-                    "type": "m.tag",
-                    "content": {"tags": {"work": {"order": "1"}}}
-                }]
-              }
               schema:
                 title: RoomInfo
                 type: object
                 properties:
                   room_id:
                     type: string
-                description: "The ID of this room."
+                    description: The ID of this room.
                   membership:
                     type: string
-                description: "The user's membership state in this room."
+                    description: The user's membership state in this room.
-                enum: ["invite", "join", "leave", "ban"]
+                    enum:
+                      - invite
+                      - join
+                      - leave
+                      - ban
                   messages:
                     type: object
                     title: PaginationChunk
-                description: "The pagination chunk for this room."
+                    description: The pagination chunk for this room.
                     properties:
                       start:
                         type: string
@@ -119,8 +73,10 @@ paths:
                           messages that preceded them leaving. This array
                           will consist of at most `limit` elements.
                         items:
-                      "$ref": "definitions/client_event.yaml"
+                          $ref: definitions/client_event.yaml
-                required: ["end", "chunk"]
+                    required:
+                      - end
+                      - chunk
                   state:
                     type: array
                     description: |-
@@ -129,27 +85,94 @@ paths:
                       user has left the room this will be the state of the
                       room when they left it.
                     items:
-                  "$ref": "definitions/client_event.yaml"
+                      $ref: definitions/client_event.yaml
                   visibility:
                     type: string
-                enum: ["private", "public"]
+                    enum:
+                      - private
+                      - public
                     description: |-
                       Whether this room is visible to the `/publicRooms` API
                       or not."
                   account_data:
                     type: array
-                description: |-
+                    description: The private data that this user has attached to this room.
-                  The private data that this user has attached to this room.
                     items:
                       title: Event
                       type: object
                       allOf:
-                    - "$ref": "../../event-schemas/schema/core-event-schema/event.yaml"
+                        - $ref: ../../event-schemas/schema/core-event-schema/event.yaml
-            required: ["room_id"]
+                required:
-        403:
+                  - room_id
-          description: >
+              examples:
-            You aren't a member of the room and weren't previously a
+                response:
-            member of the room.
+                  value: {
+                    "membership": "join",
+                    "messages": {
+                      "chunk": [
+                        {
+                          "room_id": "!636q39766251:example.com",
+                          "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                        },
+                        {
+                          "room_id": "!636q39766251:example.com",
+                          "$ref": "../../event-schemas/examples/m.room.message$m.file.yaml"
+                        }
+                      ],
+                      "end": "s3456_9_0",
+                      "start": "t44-3453_9_0"
+                    },
+                    "room_id": "!636q39766251:example.com",
+                    "state": [
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
+                      },
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.member.yaml"
+                      },
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.create.yaml"
+                      },
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
+                      }
+                    ],
+                    "visibility": "private",
+                    "account_data": [
+                      {
+                        "type": "m.tag",
+                        "content": {
+                          "tags": {
+                            "work": {
+                              "order": "1"
+                            }
+                          }
+                        }
+                      }
+                    ]
+                  }
+        "403":
+          description: |
+            You aren't a member of the room and weren't previously a member of the room.
       tags:
         - Room participation
       deprecated: true
+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

data/api/client-server/room_send.yaml

@@ -12,21 +12,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 message event send API"
+  title: Matrix Client-Server message event send API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/send/{eventType}/{txnId}":
     put:
@@ -44,58 +33,81 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room to send the event to.
           required: true
-          x-example: "!636q39766251:example.com"
+          example: "!636q39766251:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: eventType
           description: The type of event to send.
           required: true
-          x-example: "m.room.message"
+          example: m.room.message
+          schema:
+            type: string
         - in: path
           name: txnId
-          type: string
           description: |-
             The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate an
             ID unique across requests with the same access token; it will be
             used by the server to ensure idempotency of requests.
           required: true
-          x-example: "35"
+          example: "35"
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               example: {
                 "msgtype": "m.text",
                 "body": "hello"
               }
+        required: true
       responses:
-        200:
+        "200":
-          description: "An ID for the sent event."
+          description: An ID for the sent event.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                  "event_id": "$YUwRidLecu:example.com"
-              }
               schema:
                 type: object
                 properties:
                   event_id:
                     type: string
-                description: |-
+                    description: A unique identifier for the event.
-                  A unique identifier for the event.
                 required:
                   - event_id
-        400:
+              examples:
+                response:
+                  value: {
+                    "event_id": "$YUwRidLecu:example.com"
+                  }
+        "400":
           description: |-
             The request is invalid. A [standard error response](/client-server-api/#standard-error-response)
             will be returned. As well as the normal common error codes, other reasons for rejection include:
 
             - `M_DUPLICATE_ANNOTATION`: The request is an attempt to send a [duplicate annotation](/client-server-api/#avoiding-duplicate-annotations).
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
       tags:
         - Room participation
+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

data/api/client-server/room_state.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 state event send API"
+  title: Matrix Client-Server state event send API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/state/{eventType}/{stateKey}":
     put:
@@ -53,28 +42,31 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room to set the state in
           required: true
-          x-example: "!636q39766251:example.com"
+          example: "!636q39766251:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: eventType
           description: The type of event to send.
           required: true
-          x-example: "m.room.member"
+          example: m.room.member
-        - in: path
+          schema:
             type: string
+        - in: path
           name: stateKey
           description: |-
             The state_key for the state to send. Defaults to the empty string. When
             an empty string, the trailing slash on this endpoint is optional.
           required: true
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               example: {
@@ -82,33 +74,26 @@ paths:
                 "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF",
                 "displayname": "Alice Margatroid"
               }
+        required: true
       responses:
-        200:
+        "200":
-          description: "An ID for the sent event."
+          description: An ID for the sent event.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                  "event_id": "$YUwRidLecu:example.com"
-              }
               schema:
                 type: object
                 properties:
                   event_id:
                     type: string
-                description: |-
+                    description: A unique identifier for the event.
-                  A unique identifier for the event.
                 required:
                   - event_id
-        403:
-          description: |-
-            The sender doesn't have permission to send the event into the room.
-          schema:
-            $ref: "definitions/errors/error.yaml"
               examples:
-            application/json: {
+                response:
-              "errcode": "M_FORBIDDEN",
+                  value: {
-              "error": "You do not have permission to send the event."
+                    "event_id": "$YUwRidLecu:example.com"
                   }
-        400:
+        "400":
           description: |-
             The sender's request is malformed.
 
@@ -119,12 +104,42 @@ paths:
 
             * `M_BAD_ALIAS`: One or more aliases within the `m.room.canonical_alias` event
               do not point to the room ID for which the state event is to be sent to.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_BAD_ALIAS",
                     "error": "The alias '#hello:example.org' does not point to this room."
                   }
+        "403":
+          description: The sender doesn't have permission to send the event into the room.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You do not have permission to send the event."
+                  }
       tags:
         - Room participation
+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

data/api/client-server/room_upgrades.yaml

@@ -11,82 +11,99 @@
 # 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 Upgrades API"
+  title: Matrix Client-Server Room Upgrades API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/upgrade":
     post:
       summary: Upgrades a room to a new room version.
-      description: |-
+      description: Upgrades the given room to a particular room version.
-        Upgrades the given room to a particular room version.
       operationId: upgradeRoom
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           required: true
           description: The ID of the room to upgrade.
-          x-example: "!oldroom:example.org"
+          example: "!oldroom:example.org"
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               properties:
                 new_version:
                   type: string
                   description: The new version for the room.
-            example: {"new_version": "2"}
+              example: {
-            required: [new_version]
+                "new_version": "2"
+              }
+              required:
+                - new_version
+        required: true
       responses:
-        200:
+        "200":
           description: The room was successfully upgraded.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "replacement_room": "!newroom:example.org"
-            }
               schema:
                 type: object
                 properties:
                   replacement_room:
                     type: string
                     description: The ID of the new room.
-            required: [replacement_room]
+                required:
-        400:
+                  - replacement_room
+              examples:
+                response:
+                  value: {
+                    "replacement_room": "!newroom:example.org"
+                  }
+        "400":
           description: |-
             The request was invalid. One way this can happen is if the room version
             requested is not supported by the homeserver.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_UNSUPPORTED_ROOM_VERSION",
                     "error": "This server does not support that room version"
                   }
+        "403":
+          description: The user is not permitted to upgrade the room.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
-        403:
-          description: |-
-            The user is not permitted to upgrade the room.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "You cannot upgrade this room"
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room upgrades
+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

data/api/client-server/rooms.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 Rooms API"
+  title: Matrix Client-Server Rooms API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/event/{eventId}":
     get:
@@ -38,36 +27,45 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The ID of the room the event is in.
           required: true
-          x-example: "!636q39766251:matrix.org"
+          example: "!636q39766251:matrix.org"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: eventId
           description: The event ID to get.
           required: true
-          x-example: "$asfDuShaf7Gafaw:matrix.org"
+          example: $asfDuShaf7Gafaw:matrix.org
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The full event.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/client_event.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "room_id": "!636q39766251:matrix.org",
                     "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
                   }
+        "404":
+          description: The event was not found or you do not have permission to read this
+            event.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/client_event.yaml"
+                $ref: definitions/errors/error.yaml
-        404:
-          description: The event was not found or you do not have permission to read this event.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Event not found."
                   }
-          schema:
-            "$ref": "definitions/errors/error.yaml"
       tags:
         - Room participation
   "/rooms/{roomId}/state/{eventType}/{stateKey}":
@@ -83,61 +81,80 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room to look up the state in.
           required: true
-          x-example: "!636q39766251:example.com"
+          example: "!636q39766251:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: eventType
           description: The type of state to look up.
           required: true
-          x-example: "m.room.name"
+          example: m.room.name
-        - in: path
+          schema:
             type: string
+        - in: path
           name: stateKey
           description: |-
             The key of the state to look up. Defaults to an empty string. When
             an empty string, the trailing slash on this endpoint is optional.
           required: true
-          x-example: ""
+          example: ""
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The content of the state event.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "name": "Example room name"}
               schema:
                 type: object
-        404:
+              examples:
+                response:
+                  value: {
+                    "name": "Example room name"
+                  }
+        "403":
+          description: |
+            You aren't a member of the room and weren't previously a member of the room.
+        "404":
           description: The room has no state with the given type or key.
-        403:
-          description: >
-            You aren't a member of the room and weren't previously a
-            member of the room.
       tags:
         - Room participation
   "/rooms/{roomId}/state":
     get:
       summary: Get all state events in the current state of a room.
-      description: |-
+      description: Get the state events for the current state of a room.
-        Get the state events for the current state of a room.
       operationId: getRoomState
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room to look up the state for.
           required: true
-          x-example: "!636q39766251:example.com"
+          example: "!636q39766251:example.com"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The current state of the room
+          content:
+            application/json:
+              schema:
+                type: array
+                title: RoomState
+                description: |-
+                  If the user is a member of the room this will be the
+                  current state of the room as a list of events. If the user
+                  has left the room then this will be the state of the room
+                  when they left as a list of events.
+                items:
+                  $ref: definitions/client_event.yaml
               examples:
-            application/json: [
+                response:
+                  value: [
                     {
                       "room_id": "!636q39766251:example.com",
                       "$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
@@ -155,49 +172,46 @@ paths:
                       "$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
                     }
                   ]
-          schema:
+        "403":
-            type: array
+          description: |
-            title: RoomState
+            You aren't a member of the room and weren't previously a member of the room.
-            description: |-
-              If the user is a member of the room this will be the
-              current state of the room as a list of events. If the user
-              has left the room then this will be the state of the room
-              when they left as a list of events.
-            items:
-              $ref: "definitions/client_event.yaml"
-        403:
-          description: >
-            You aren't a member of the room and weren't previously a
-            member of the room.
       tags:
         - Room participation
   "/rooms/{roomId}/members":
     get:
       summary: Get the m.room.member events for the room.
-      description:
+      description: Get the list of members for this room.
-        Get the list of members for this room.
       operationId: getMembersByRoom
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room to get the member events for.
           required: true
-          x-example: "!636q39766251:example.com"
+          example: "!636q39766251:example.com"
+          schema:
+            type: string
         - in: query
           name: at
-          type: string
           description: |-
             The point in time (pagination token) to return members for in the room.
             This token can be obtained from a `prev_batch` token returned for
             each room by the sync API. Defaults to the current state of the room,
             as determined by the server.
-          x-example: "YWxsCgpOb25lLDM1ODcwOA"
+          example: YWxsCgpOb25lLDM1ODcwOA
+          schema:
+            type: string
         # XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON
         # filter might be a better alternative.
         # See https://github.com/matrix-org/matrix-doc/issues/1337
         - in: query
           name: membership
+          description: |-
+            The kind of membership to filter for. Defaults to no filtering if
+            unspecified. When specified alongside `not_membership`, the two
+            parameters create an 'or' condition: either the membership *is*
+            the same as `membership` **or** *is not* the same as `not_membership`.
+          example: join
+          schema:
             type: string
             enum:
               - join
@@ -205,14 +219,13 @@ paths:
               - knock
               - leave
               - ban
-          description: |-
-            The kind of membership to filter for. Defaults to no filtering if
-            unspecified. When specified alongside `not_membership`, the two
-            parameters create an 'or' condition: either the membership *is*
-            the same as `membership` **or** *is not* the same as `not_membership`.
-          x-example: "join"
         - in: query
           name: not_membership
+          description: |-
+            The kind of membership to exclude from the results. Defaults to no
+            filtering if unspecified.
+          example: leave
+          schema:
             type: string
             enum:
               - join
@@ -220,20 +233,26 @@ paths:
               - knock
               - leave
               - ban
-          description: |-
-            The kind of membership to exclude from the results. Defaults to no
-            filtering if unspecified.
-          x-example: leave
       security:
         - accessToken: []
       responses:
-        200:
+        "200":
           description: |-
             A list of members of the room. If you are joined to the room then
             this will be the current members of the room. If you have left the
             room then this will be the members of the room when you left.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  chunk:
+                    type: array
+                    items:
+                      $ref: definitions/client_event.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "chunk": [
                       {
                         "room_id": "!636q39766251:example.com",
@@ -241,48 +260,36 @@ paths:
                       }
                     ]
                   }
-          schema:
+        "403":
-            type: object
+          description: |
-            properties:
+            You aren't a member of the room and weren't previously a member of the room.
-              chunk:
-                type: array
-                items:
-                  $ref: "definitions/client_event.yaml"
-        403:
-          description: >
-            You aren't a member of the room and weren't previously a
-            member of the room.
       tags:
         - Room participation
   "/rooms/{roomId}/joined_members":
     get:
       summary: Gets the list of currently joined users and their profile data.
-      description:
+      description: This API returns a map of MXIDs to member info objects for members
-        This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room.
+        of the room. The current user must be in the room for it to work, unless
-        This API is primarily for Application Services and should be faster to respond than `/members` as it can be implemented more efficiently on the server.
+        it is an Application Service in which case any of the AS's users must be
+        in the room. This API is primarily for Application Services and should
+        be faster to respond than `/members` as it can be implemented more
+        efficiently on the server.
       operationId: getJoinedMembersByRoom
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room to get the members of.
           required: true
-          x-example: "!636q39766251:example.com"
+          example: "!636q39766251:example.com"
+          schema:
+            type: string
       security:
         - accessToken: []
       responses:
-        200:
+        "200":
-          description: |-
+          description: A map of MXID to room member objects.
-            A map of MXID to room member objects.
+          content:
-          examples:
+            application/json:
-            application/json: {
-                "joined": {
-                  "@bar:example.com": {
-                    "display_name": "Bar",
-                    "avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK"
-                  }
-                }
-              }
               schema:
                 type: object
                 properties:
@@ -297,11 +304,37 @@ paths:
                         avatar_url:
                           type: string
                           format: uri
-                      description: The avatar of the user this object is representing, as an [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris).
+                          description: The avatar of the user this object is representing, as an [`mxc://`
+                            URI](/client-server-api/#matrix-content-mxc-uris).
                     description: A map from user ID to a RoomMember object.
                     type: object
-        403:
+              examples:
-          description: >
+                response:
+                  value: {
+                    "joined": {
+                      "@bar:example.com": {
+                        "display_name": "Bar",
+                        "avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK"
+                      }
+                    }
+                  }
+        "403":
+          description: |
             You aren't a member of the room.
       tags:
         - Room participation
+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

data/api/client-server/search.yaml

@@ -11,41 +11,30 @@
 # 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 Search API"
+  title: Matrix Client-Server Search API
-  version: "1.0.0"
+  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
 paths:
-  "/search":
+  /search:
     post:
       summary: Perform a server-side search.
-      description: |-
+      description: Performs a full text search across different categories.
-        Performs a full text search across different categories.
       operationId: search
       security:
         - accessToken: []
       parameters:
         - in: query
           name: next_batch
-          type: string
           description: |-
             The point to return events from. If given, this should be a
             `next_batch` result from a previous call to this endpoint.
-          x-example: "YWxsCgpOb25lLDM1ODcwOA"
+          example: YWxsCgpOb25lLDM1ODcwOA
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               example: {
@@ -69,9 +58,8 @@ paths:
               properties:
                 search_categories:
                   type: object
-                title: "Categories"
+                  title: Categories
-                description: Describes which categories to search in and
+                  description: Describes which categories to search in and their criteria.
-                  their criteria.
                   properties:
                     room_events:
                       type: object
@@ -85,19 +73,23 @@ paths:
                           type: array
                           items:
                             type: string
-                          enum: ["content.body", "content.name", "content.topic"]
+                            enum:
+                              - content.body
+                              - content.name
+                              - content.topic
                           description: The keys to search. Defaults to all.
                         filter:
                           type: object
                           title: Filter
-                        description: |-
+                          description: This takes a [filter](/client-server-api/#filtering).
-                          This takes a [filter](/client-server-api/#filtering).
                           allOf:
-                          - $ref: "definitions/room_event_filter.yaml"
+                            - $ref: definitions/room_event_filter.yaml
                         order_by:
-                        title: "Ordering"
+                          title: Ordering
                           type: string
-                        enum: ["recent", "rank"]
+                          enum:
+                            - recent
+                            - rank
                           description: |-
                             The order in which to search for results.
                             By default, this is `"rank"`.
@@ -110,19 +102,19 @@ paths:
                           properties:
                             before_limit:
                               type: integer
-                                title: "Before limit"
+                              title: Before limit
                               description: |-
                                 How many events before the result are
                                 returned. By default, this is `5`.
                             after_limit:
                               type: integer
-                                title: "After limit"
+                              title: After limit
                               description: |-
                                 How many events after the result are
                                 returned. By default, this is `5`.
                             include_profile:
                               type: boolean
-                                title: "Return profile information"
+                              title: Return profile information
                               description: |-
                                 Requests that the server returns the
                                 historic profile information for the users
@@ -153,24 +145,30 @@ paths:
                                   key:
                                     type: string
                                     title: Group Key
-                                  description: |-
+                                    description: Key that defines the group.
-                                    Key that defines the group.
+                                    enum:
-                                  enum: ["room_id", "sender"]
+                                      - room_id
-                    required: ["search_term"]
+                                      - sender
-            required: ["search_categories"]
+                      required:
+                        - search_term
+              required:
+                - search_categories
+        required: true
       responses:
-        200:
+        "200":
           description: Results of the search.
+          content:
+            application/json:
               schema:
                 type: object
                 title: Results
-            required: ["search_categories"]
+                required:
+                  - search_categories
                 properties:
                   search_categories:
                     type: object
                     title: Result Categories
-                description: Describes which categories to search in and
+                    description: Describes which categories to search in and their criteria.
-                  their criteria.
                     properties:
                       room_events:
                         type: object
@@ -183,7 +181,8 @@ paths:
                           highlights:
                             type: array
                             title: Highlights
-                        description: List of words which should be highlighted, useful for stemming which may change the query terms.
+                            description: List of words which should be highlighted, useful for stemming
+                              which may change the query terms.
                             items:
                               type: string
                           results:
@@ -197,15 +196,14 @@ paths:
                               properties:
                                 rank:
                                   type: number
-                              description: A number that describes how closely
+                                  description: A number that describes how closely this result matches the search.
-                                this result matches the search. Higher is
+                                    Higher is closer.
-                                closer.
                                 result:
                                   type: object
                                   title: Event
                                   description: The event that matched.
                                   allOf:
-                                - "$ref": "definitions/client_event.yaml"
+                                    - $ref: definitions/client_event.yaml
                                 context:
                                   type: object
                                   title: Event Context
@@ -214,13 +212,11 @@ paths:
                                     start:
                                       type: string
                                       title: Start Token
-                                  description: |-
+                                      description: Pagination token for the start of the chunk
-                                    Pagination token for the start of the chunk
                                     end:
                                       type: string
                                       title: End Token
-                                  description: |-
+                                      description: Pagination token for the end of the chunk
-                                    Pagination token for the end of the chunk
                                     profile_info:
                                       type: object
                                       title: Profile Information
@@ -248,7 +244,7 @@ paths:
                                       items:
                                         title: Event
                                         type: object
-                                    "$ref": "definitions/client_event.yaml"
+                                        $ref: definitions/client_event.yaml
                                     events_after:
                                       type: array
                                       title: Events After
@@ -256,7 +252,7 @@ paths:
                                       items:
                                         title: Event
                                         type: object
-                                    "$ref": "definitions/client_event.yaml"
+                                        $ref: definitions/client_event.yaml
                           state:
                             type: object
                             title: Current state
@@ -271,7 +267,7 @@ paths:
                               type: array
                               title: Room State
                               items:
-                            "$ref": "definitions/client_event.yaml"
+                                $ref: definitions/client_event.yaml
                           groups:
                             type: object
                             title: Groups
@@ -288,8 +284,7 @@ paths:
                               additionalProperties:
                                 type: object
                                 title: Group Value
-                            description: |-
+                                description: The results for a particular group value.
-                                The results for a particular group value.
                                 properties:
                                   next_batch:
                                     type: string
@@ -308,8 +303,7 @@ paths:
                                       groups.
                                   results:
                                     type: array
-                                description: |-
+                                    description: Which results are in this group.
-                                  Which results are in this group.
                                     items:
                                       type: string
                                       title: Result Event ID
@@ -322,7 +316,8 @@ paths:
                               the next call. If this field is absent, there are no
                               more results.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "search_categories": {
                       "room_events": {
                         "groups": {
@@ -355,11 +350,28 @@ paths:
                       }
                     }
                   }
-        400:
+        "400":
           description: Part of the request was invalid.
-        429:
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Search
+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

data/api/client-server/space_hierarchy.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 Space Hierarchy API"
+  title: Matrix Client-Server Space Hierarchy API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/rooms/{roomId}/hierarchy":
     get:
@@ -44,30 +33,32 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room ID of the space to get a hierarchy for.
           required: true
-          x-example: "!space:example.org"
+          example: "!space:example.org"
+          schema:
+            type: string
         - in: query
-          type: boolean
           name: suggested_only
           description: |-
             Optional (default `false`) flag to indicate whether or not the server should only consider
             suggested rooms. Suggested rooms are annotated in their [`m.space.child`](#mspacechild) event
             contents.
-          x-example: true
+          example: true
+          schema:
+            type: boolean
         - in: query
-          type: integer
           name: limit
           description: |-
             Optional limit for the maximum number of rooms to include per response. Must be an integer
             greater than zero.
 
             Servers should apply a default value, and impose a maximum value to avoid resource exhaustion.
-          x-example: 20
+          example: 20
-        - in: query
+          schema:
             type: integer
+        - in: query
           name: max_depth
           description: |-
             Optional limit for how far to go into the space. Must be a non-negative integer.
@@ -75,65 +66,39 @@ paths:
             When reached, no further child rooms will be returned.
 
             Servers should apply a default value, and impose a maximum value to avoid resource exhaustion.
-          x-example: 5
+          example: 5
+          schema:
+            type: integer
         - in: query
-          type: string
           name: from
           description: |-
             A pagination token from a previous result. If specified, `max_depth` and `suggested_only` cannot
             be changed from the first request.
-          x-example: "next_batch_token"
+          example: next_batch_token
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description: |-
+          description: A portion of the space tree, starting at the provided room ID.
-            A portion of the space tree, starting at the provided room ID.
+          content:
-          examples:
+            application/json:
-            application/json: {
-              "rooms": [
-                {
-                  "room_id": "!space:example.org",
-                  "avatar_url": "mxc://example.org/abcdef",
-                  "guest_can_join": false,
-                  "name": "The First Space",
-                  "topic": "No other spaces were created first, ever",
-                  "world_readable": true,
-                  "join_rule": "public",
-                  "room_type": "m.space",
-                  "num_joined_members": 42,
-                  "canonical_alias": "#general:example.org",
-                  "children_state": [
-                    {
-                      "type": "m.space.child",
-                      "state_key": "!a:example.org",
-                      "content": {
-                        "via": ["example.org"]
-                      },
-                      "sender": "@alice:example.org",
-                      "origin_server_ts": 1629413349153
-                    }
-                  ]
-                }
-              ],
-              "next_batch": "next_batch_token"
-            }
               schema:
                 type: object
                 properties:
                   rooms:
                     type: array
-                description: |-
+                    description: The rooms for the current page, with the current filters.
-                  The rooms for the current page, with the current filters.
                     items:
                       allOf:
-                    - $ref: "definitions/public_rooms_chunk.yaml"
+                        - $ref: definitions/public_rooms_chunk.yaml
                         - type: object
                           title: ChildRoomsChunk
                           properties:
-                        # Override x-addedInMatrixVersion for room_type (this endpoint had it first)
                             room_type:
                               type: string
-                          description: |-
+                              description: The `type` of room (from
-                            The `type` of room (from [`m.room.create`](/client-server-api/#mroomcreate)), if any.
+                                [`m.room.create`](/client-server-api/#mroomcreate)),
+                                if any.
                             children_state:
                               type: array
                               description: |-
@@ -143,7 +108,7 @@ paths:
                                 If the room is not a space-room, this should be empty.
                               items:
                                 allOf:
-                              - $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
+                                  - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
                                   - type: object
                                     title: StrippedChildStateEvent
                                     properties:
@@ -151,46 +116,104 @@ paths:
                                         type: integer
                                         format: int64
                                         description: The `origin_server_ts` for the event.
-                                required: [origin_server_ts]
+                                    required:
-                      required: [children_state]
+                                      - origin_server_ts
+                          required:
+                            - children_state
                   next_batch:
                     type: string
                     description: |-
                       A token to supply to `from` to keep paginating the responses. Not present when there are
                       no further results.
-            required: [rooms]
+                required:
-        403:
+                  - rooms
-          description: |-
-            The user cannot view or peek 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 peeking.
-            - The user has been banned from the room.
-            - The room does not exist.
               examples:
-            application/json: {
+                response:
-              "errcode": "M_FORBIDDEN",
+                  value: {
-              "error": "You are not allowed to view this room."
+                    "rooms": [
+                      {
+                        "room_id": "!space:example.org",
+                        "avatar_url": "mxc://example.org/abcdef",
+                        "guest_can_join": false,
+                        "name": "The First Space",
+                        "topic": "No other spaces were created first, ever",
+                        "world_readable": true,
+                        "join_rule": "public",
+                        "room_type": "m.space",
+                        "num_joined_members": 42,
+                        "canonical_alias": "#general:example.org",
+                        "children_state": [
+                          {
+                            "type": "m.space.child",
+                            "state_key": "!a:example.org",
+                            "content": {
+                              "via": [
+                                "example.org"
+                              ]
+                            },
+                            "sender": "@alice:example.org",
+                            "origin_server_ts": 1629413349153
                           }
-          schema:
+                        ]
-            "$ref": "definitions/errors/error.yaml"
+                      }
-        400:
+                    ],
+                    "next_batch": "next_batch_token"
+                  }
+        "400":
           description: |-
             The request was invalid in some way. A meaningful `errcode`
             and description error text will be returned. Example reasons for rejection are:
 
             - The `from` token is unknown to the server.
             - `suggested_only` or `max_depth` changed during pagination.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_INVALID_PARAM",
                     "error": "suggested_only and max_depth cannot change on paginated requests"
                   }
+        "403":
+          description: |-
+            The user cannot view or peek 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 peeking.
+            - The user has been banned from the room.
+            - The room does not exist.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
-        429:
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not allowed to view this room."
+                  }
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Spaces
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/client-server/sso_login_redirect.yaml

@@ -11,17 +11,12 @@
 # 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 SSO Login API"
+  title: Matrix Client-Server SSO Login API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v3
 paths:
-  "/login/sso/redirect":
+  /login/sso/redirect:
     get:
       x-addedInMatrixVersion: "1.1"
       summary: Redirect the user's browser to the SSO interface.
@@ -35,18 +30,20 @@ paths:
       operationId: redirectToSSO
       parameters:
         - in: query
-          type: string
           name: redirectUrl
           description: |-
             URI to which the user will be redirected after the homeserver has
             authenticated the user with SSO.
           required: true
+          schema:
+            type: string
       responses:
-        302:
+        "302":
           description: A redirect to the SSO interface.
           headers:
             Location:
-              type: "string"
+              schema:
+                type: string
       tags:
         - Session management
   "/login/sso/redirect/{idpId}":
@@ -63,29 +60,44 @@ paths:
       operationId: redirectToIdP
       parameters:
         - in: path
-          type: string
           name: idpId
           required: true
           description: |-
             The `id` of the IdP from the `m.login.sso` `identity_providers`
             array denoting the user's selection.
-        - in: query
+          schema:
             type: string
+        - in: query
           name: redirectUrl
           description: |-
             URI to which the user will be redirected after the homeserver has
             authenticated the user with SSO.
           required: true
+          schema:
+            type: string
       responses:
-        302:
+        "302":
           description: A redirect to the SSO interface.
           headers:
             Location:
-              type: "string"
+              schema:
-        404:
+                type: string
+        "404":
           description: |-
             The IdP ID was not recognized by the server. The server is encouraged
             to provide a user-friendly page explaining the error given the user
             will be navigated to it.
       tags:
         - Session management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3

data/api/client-server/sync.yaml

@@ -11,22 +11,12 @@
 # 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 sync API"
+  title: Matrix Client-Server sync API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-basePath: /_matrix/client/v3
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/sync":
+  /sync:
     get:
       summary: Synchronise the client's state and receive new messages.
       description: |-
@@ -57,7 +47,6 @@ paths:
       parameters:
         - in: query
           name: filter
-          type: string
           description: |-
             The ID of a filter created using the filter API or a filter JSON
             object encoded as a string. The server will detect whether it is
@@ -68,17 +57,19 @@ paths:
             long poll requests.
 
             See [Filtering](/client-server-api/#filtering) for more information.
-          x-example: "66696p746572"
+          example: 66696p746572
+          schema:
+            type: string
         - in: query
           name: since
-          type: string
           description: |-
             A point in time to continue a sync from. This should be the
             `next_batch` token returned by an earlier call to this endpoint.
-          x-example: "s72594_4483_1934"
+          example: s72594_4483_1934
+          schema:
+            type: string
         - in: query
           name: full_state
-          type: boolean
           description: |-
             Controls whether to include the full state for all rooms the user
             is a member of.
@@ -93,11 +84,11 @@ paths:
             changed since the point indicated by `since` will be returned.
 
             By default, this is `false`.
-          x-example: "false"
+          example: "false"
+          schema:
+            type: boolean
         - in: query
           name: set_presence
-          type: string
-          enum: ["offline", "online", "unavailable"]
           description: |-
             Controls whether the client is automatically marked as online by
             polling this API. If this parameter is omitted then the client is
@@ -105,10 +96,15 @@ paths:
             the parameter is set to "offline" then the client is not marked as
             being online when it uses this API. When set to "unavailable", the
             client is marked as being idle.
-          x-example: "offline"
+          example: offline
+          schema:
+            type: string
+            enum:
+              - offline
+              - online
+              - unavailable
         - in: query
           name: timeout
-          type: integer
           description: |-
             The maximum time to wait, in milliseconds, before returning this
             request. If no events (or other data) become available before this
@@ -116,12 +112,15 @@ paths:
 
             By default, this is `0`, so the server will return immediately
             even if the response is empty.
-          x-example: 30000
+          example: 30000
+          schema:
+            type: integer
       responses:
-        200:
+        "200":
-          description:
+          description: The initial snapshot or delta for the client to use to update their
-            The initial snapshot or delta for the client to use to update their
             state.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -133,8 +132,7 @@ paths:
                   rooms:
                     title: Rooms
                     type: object
-                description: |-
+                    description: Updates to rooms.
-                  Updates to rooms.
                     properties:
                       join:
                         title: Joined Rooms
@@ -153,7 +151,7 @@ paths:
                                 Information about the room which clients may need to
                                 correctly render it to users.
                               properties:
-                            "m.heroes":
+                                m.heroes:
                                   type: array
                                   description: |-
                                     The users which can be used to generate a room name
@@ -177,14 +175,14 @@ paths:
                                     field may be omitted.
                                   items:
                                     type: string
-                            "m.joined_member_count":
+                                m.joined_member_count:
                                   type: integer
                                   description: |-
                                     The number of users with `membership` of `join`,
                                     including the client's own user ID. If this field has
                                     not changed since the last sync, it may be omitted.
                                     Required otherwise.
-                            "m.invited_member_count":
+                                m.invited_member_count:
                                   type: integer
                                   description: |-
                                     The number of users with `membership` of `invite`.
@@ -206,7 +204,7 @@ paths:
                                 required to display the senders of the timeline events
                                 in this response.
                               allOf:
-                            - $ref: "definitions/state_event_batch.yaml"
+                                - $ref: definitions/state_event_batch.yaml
                             timeline:
                               title: Timeline
                               type: object
@@ -214,7 +212,7 @@ paths:
                                 The timeline of messages and state changes in the
                                 room.
                               allOf:
-                            - $ref: "definitions/timeline_batch.yaml"
+                                - $ref: definitions/timeline_batch.yaml
                             ephemeral:
                               title: Ephemeral
                               type: object
@@ -225,7 +223,7 @@ paths:
                                 [typing notification](#typing-notifications) and
                                 [read receipt](#receipts) events.
                               allOf:
-                            - $ref: "definitions/event_batch.yaml"
+                                - $ref: definitions/event_batch.yaml
                             account_data:
                               title: Account Data
                               type: object
@@ -233,7 +231,7 @@ paths:
                                 The private data that this user has attached to
                                 this room.
                               allOf:
-                          - $ref: "definitions/event_batch.yaml"
+                                - $ref: definitions/event_batch.yaml
                             unread_notifications:
                               title: Unread Notification Counts
                               type: object
@@ -246,20 +244,19 @@ paths:
                                 these counts will only be for the main timeline rather than all events in the room.
                                 See the [threading module](#threading) for more information.
                               x-changedInMatrixVersion:
-                            1.4: |
+                                "1.4": |
                                   Updated to reflect behaviour of having `unread_thread_notifications` as `true` in
                                   the `RoomEventFilter` for `/sync`.
                               properties:
                                 highlight_count:
                                   title: Highlighted notification count
                                   type: integer
-                                description: The number of unread notifications
+                                  description: The number of unread notifications for this room with the highlight
-                                             for this room with the highlight flag set.
+                                    flag set.
                                 notification_count:
                                   title: Total notification count
                                   type: integer
-                                description: The total number of unread notifications
+                                  description: The total number of unread notifications for this room.
-                                             for this room.
                             unread_thread_notifications:
                               title: Unread Thread Notification Counts
                               type: object
@@ -278,13 +275,12 @@ paths:
                                   highlight_count:
                                     title: ThreadedHighlightNotificationCount
                                     type: integer
-                                description: |-
+                                    description: The number of unread notifications for this *thread* with the
-                                  The number of unread notifications for this *thread* with the highlight flag set.
+                                      highlight flag set.
                                   notification_count:
                                     title: ThreadedTotalNotificationCount
                                     type: integer
-                                description: |-
+                                    description: The total number of unread notifications for this *thread*.
-                                  The total number of unread notifications for this *thread*.
                       invite:
                         title: Invited Rooms
                         type: object
@@ -303,15 +299,16 @@ paths:
                                 to.
                               properties:
                                 events:
-                              description: The [stripped state events](#stripped-state) that form the invite state.
+                                  description: The [stripped state events](#stripped-state) that form the invite
+                                    state.
                                   items:
-                                $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
+                                    $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
                                   type: array
                       knock:
                         title: Knocked rooms
                         type: object
-                    description: |-
+                        description: The rooms that the user has knocked upon, mapped as room ID to room
-                      The rooms that the user has knocked upon, mapped as room ID to room information.
+                          information.
                         additionalProperties:
                           title: Knocked Room
                           type: object
@@ -319,13 +316,14 @@ paths:
                             knock_state:
                               title: KnockState
                               type: object
-                          description: |-
+                              description: The [stripped state](#stripped-state) of a room that the user has
-                            The [stripped state](#stripped-state) of a room that the user has knocked upon.
+                                knocked upon.
                               properties:
                                 events:
-                              description: The [stripped state events](#stripped-state) that form the knock state.
+                                  description: The [stripped state events](#stripped-state) that form the knock
+                                    state.
                                   items:
-                                $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
+                                    $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
                                   type: array
                       leave:
                         title: Left rooms
@@ -340,10 +338,9 @@ paths:
                             state:
                               title: State
                               type: object
-                          description: |-
+                              description: The state updates for the room up to the start of the timeline.
-                            The state updates for the room up to the start of the timeline.
                               allOf:
-                            - $ref: "definitions/state_event_batch.yaml"
+                                - $ref: definitions/state_event_batch.yaml
                             timeline:
                               title: Timeline
                               type: object
@@ -351,7 +348,7 @@ paths:
                                 The timeline of messages and state changes in the
                                 room up to the point when the user left.
                               allOf:
-                            - $ref: "definitions/timeline_batch.yaml"
+                                - $ref: definitions/timeline_batch.yaml
                             account_data:
                               title: Account Data
                               type: object
@@ -359,21 +356,19 @@ paths:
                                 The private data that this user has attached to
                                 this room.
                               allOf:
-                          - $ref: "definitions/event_batch.yaml"
+                                - $ref: definitions/event_batch.yaml
                   presence:
                     title: Presence
                     type: object
-                description: |-
+                    description: The updates to the presence status of other users.
-                  The updates to the presence status of other users.
                     allOf:
-                  - $ref: "definitions/event_batch.yaml"
+                      - $ref: definitions/event_batch.yaml
                   account_data:
                     title: Account Data
                     type: object
-                description: |-
+                    description: The global private data created by this user.
-                  The global private data created by this user.
                     allOf:
-                  - $ref: "definitions/event_batch.yaml"
+                      - $ref: definitions/event_batch.yaml
                   to_device:
                     title: ToDevice
                     type: object
@@ -397,11 +392,14 @@ paths:
                 required:
                   - next_batch
               examples:
-            application/json: {
+                response:
+                  value: {
                     "next_batch": "s72595_4483_1934",
                     "presence": {
                       "events": [
-                    {"$ref": "../../event-schemas/examples/m.presence.yaml"}
+                        {
+                          "$ref": "../../event-schemas/examples/m.presence.yaml"
+                        }
                       ]
                     },
                     "account_data": {
@@ -446,13 +444,19 @@ paths:
                           },
                           "ephemeral": {
                             "events": [
-                          {"$ref": "../../event-schemas/examples/m.typing.yaml"},
+                              {
-                          {"$ref": "../../event-schemas/examples/m.receipt.yaml"}
+                                "$ref": "../../event-schemas/examples/m.typing.yaml"
+                              },
+                              {
+                                "$ref": "../../event-schemas/examples/m.receipt.yaml"
+                              }
                             ]
                           },
                           "account_data": {
                             "events": [
-                          {"$ref": "../../event-schemas/examples/m.tag.yaml"},
+                              {
+                                "$ref": "../../event-schemas/examples/m.tag.yaml"
+                              },
                               {
                                 "type": "org.example.custom.room.config",
                                 "content": {
@@ -481,13 +485,17 @@ paths:
                                 "sender": "@alice:example.com",
                                 "type": "m.room.name",
                                 "state_key": "",
-                            "content": {"name": "My Room Name"}
+                                "content": {
+                                  "name": "My Room Name"
+                                }
                               },
                               {
                                 "sender": "@alice:example.com",
                                 "type": "m.room.member",
                                 "state_key": "@bob:example.com",
-                            "content": {"membership": "invite"}
+                                "content": {
+                                  "membership": "invite"
+                                }
                               }
                             ]
                           }
@@ -501,13 +509,17 @@ paths:
                                 "sender": "@alice:example.com",
                                 "type": "m.room.name",
                                 "state_key": "",
-                            "content": {"name": "My Room Name"}
+                                "content": {
+                                  "name": "My Room Name"
+                                }
                               },
                               {
                                 "sender": "@bob:example.com",
                                 "type": "m.room.member",
                                 "state_key": "@bob:example.com",
-                            "content": {"membership": "knock"}
+                                "content": {
+                                  "membership": "knock"
+                                }
                               }
                             ]
                           }
@@ -518,3 +530,18 @@ paths:
                   }
       tags:
         - Room participation
+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

data/api/client-server/tags.yaml

@@ -12,50 +12,40 @@
 # 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 tag API"
+  title: Matrix Client-Server tag API
-  version: "1.0.0"
+  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
 paths:
   "/user/{userId}/rooms/{roomId}/tags":
     get:
       summary: List the tags for a room.
-      description: |-
+      description: List the tags set by a user on a room.
-        List the tags set by a user on a room.
       operationId: getRoomTags
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           required: true
           description: |-
             The id of the user to get tags for. The access token must be
             authorized to make requests for this user ID.
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: roomId
           required: true
-          description: |-
+          description: The ID of the room to get tags for.
-            The ID of the room to get tags for.
+          example: "!726s6s6q:example.com"
-          x-example: "!726s6s6q:example.com"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description:
+          description: The list of tags for the user for the room.
-            The list of tags for the user for the room.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -73,10 +63,15 @@ paths:
                             position of the room under the given tag.
                       additionalProperties: true
               examples:
-            application/json: {
+                response:
+                  value: {
                     "tags": {
-                "m.favourite": {"order": 0.1},
+                      "m.favourite": {
-                "u.Work": {"order": 0.7},
+                        "order": 0.1
+                      },
+                      "u.Work": {
+                        "order": 0.7
+                      },
                       "u.Customers": {}
                     }
                   }
@@ -85,39 +80,37 @@ paths:
   "/user/{userId}/rooms/{roomId}/tags/{tag}":
     put:
       summary: Add a tag to a room.
-      description: |-
+      description: Add a tag to the room.
-        Add a tag to the room.
       operationId: setRoomTag
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           required: true
           description: |-
             The id of the user to add a tag for. The access token must be
             authorized to make requests for this user ID.
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: roomId
           required: true
-          description: |-
+          description: The ID of the room to add a tag to.
-            The ID of the room to add a tag to.
+          example: "!726s6s6q:example.com"
-          x-example: "!726s6s6q:example.com"
+          schema:
-        - in: path
             type: string
+        - in: path
           name: tag
           required: true
-          description: |-
+          description: The tag to add.
-            The tag to add.
+          example: u.work
-          x-example: "u.work"
+          schema:
-        - in: body
+            type: string
-          name: body
+      requestBody:
-          required: true
+        content:
-          description: |-
+          application/json:
-            Extra data for the tag, e.g. ordering.
             schema:
               type: object
               properties:
@@ -131,53 +124,74 @@ paths:
               example: {
                 "order": 0.25
               }
+        description: Extra data for the tag, e.g. ordering.
+        required: true
       responses:
-        200:
+        "200":
-          description:
+          description: The tag was successfully added.
-            The tag was successfully added.
+          content:
+            application/json:
               schema:
                 type: object
               examples:
-            application/json: {}
+                response:
+                  value: {}
       tags:
         - User data
     delete:
       summary: Remove a tag from the room.
-      description: |-
+      description: Remove a tag from the room.
-        Remove a tag from the room.
       operationId: deleteRoomTag
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           required: true
           description: |-
             The id of the user to remove a tag for. The access token must be
             authorized to make requests for this user ID.
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: roomId
           required: true
-          description: |-
+          description: The ID of the room to remove a tag from.
-            The ID of the room to remove a tag from.
+          example: "!726s6s6q:example.com"
-          x-example: "!726s6s6q:example.com"
+          schema:
-        - in: path
             type: string
+        - in: path
           name: tag
           required: true
-          description: |-
+          description: The tag to remove.
-            The tag to remove.
+          example: u.work
-          x-example: "u.work"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description:
+          description: The tag was successfully removed.
-            The tag was successfully removed.
+          content:
+            application/json:
               schema:
                 type: object
               examples:
-            application/json: {}
+                response:
+                  value: {}
       tags:
         - User data
+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

data/api/client-server/third_party_lookup.yaml

@@ -11,23 +11,12 @@
 # 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 Third-party Lookup API"
+  title: Matrix Client-Server Third-party Lookup API
-  version: "1.0.0"
+  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
 paths:
-  "/thirdparty/protocols":
+  /thirdparty/protocols:
     get:
       summary: Retrieve metadata about all protocols that a homeserver supports.
       description: |-
@@ -38,8 +27,10 @@ paths:
       security:
         - accessToken: []
       responses:
-        200:
+        "200":
           description: The protocols supported by the homeserver.
+          content:
+            application/json:
               schema:
                 $ref: ../application-service/definitions/protocol_metadata.yaml
       tags:
@@ -47,32 +38,37 @@ paths:
   "/thirdparty/protocol/{protocol}":
     get:
       summary: Retrieve metadata about a specific protocol that the homeserver supports.
-      description: |-
+      description: Fetches the metadata from the homeserver about a particular
-        Fetches the metadata from the homeserver about a particular third-party protocol.
+        third-party protocol.
       operationId: getProtocolMetadata
       security:
         - accessToken: []
       parameters:
         - in: path
           name: protocol
-          type: string
+          description: The name of the protocol.
-          description: |-
-            The name of the protocol.
           required: true
-          x-example: "irc"
+          example: irc
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The protocol was found and metadata returned.
+          content:
+            application/json:
               schema:
                 $ref: ../application-service/definitions/protocol.yaml
-        404:
+        "404":
           description: The protocol is unknown.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND"
                   }
-          schema:
-            $ref: definitions/errors/error.yaml
       tags:
         - Third-party Lookup
   "/thirdparty/location/{protocol}":
@@ -93,29 +89,36 @@ paths:
       parameters:
         - in: path
           name: protocol
-          type: string
           description: The protocol used to communicate to the third-party network.
           required: true
-          x-example: irc
+          example: irc
+          schema:
+            type: string
         - in: query
           name: searchFields
-          type: string
           description: |-
             One or more custom fields to help identify the third-party
             location.
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: At least one portal room was found.
+          content:
+            application/json:
               schema:
                 $ref: ../application-service/definitions/location_batch.yaml
-        404:
+        "404":
           description: No portal rooms were found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND"
                   }
-          schema:
-            $ref: definitions/errors/error.yaml
       tags:
         - Third-party Lookup
   "/thirdparty/user/{protocol}":
@@ -130,32 +133,38 @@ paths:
       parameters:
         - in: path
           name: protocol
-          type: string
+          description: The name of the protocol.
-          description: |-
-            The name of the protocol.
           required: true
-          x-example: irc
+          example: irc
+          schema:
+            type: string
         - in: query
           name: fields...
+          description: One or more custom fields that are passed to the AS to help
+            identify the user.
+          schema:
             type: string
-          description: |-
-            One or more custom fields that are passed to the AS to help identify the user.
       responses:
-        200:
+        "200":
           description: The Matrix User IDs found with the given parameters.
+          content:
+            application/json:
               schema:
                 $ref: ../application-service/definitions/user_batch.yaml
-        404:
+        "404":
           description: The Matrix User ID was not found
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND"
                   }
-          schema:
-            $ref: definitions/errors/error.yaml
       tags:
         - Third-party Lookup
-  "/thirdparty/location":
+  /thirdparty/location:
     get:
       summary: Reverse-lookup third-party locations given a Matrix room alias.
       description: |-
@@ -167,54 +176,78 @@ paths:
       parameters:
         - in: query
           name: alias
-          type: string
           description: The Matrix room alias to look up.
           required: true
-          x-example: "#matrix:matrix.org"
+          example: "#matrix:matrix.org"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description: |-
+          description: All found third-party locations.
-            All found third-party locations.
+          content:
+            application/json:
               schema:
                 $ref: ../application-service/definitions/location_batch.yaml
-        404:
+        "404":
           description: The Matrix room alias was not found
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND"
                   }
-          schema:
-            $ref: definitions/errors/error.yaml
       tags:
         - Third-party Lookup
-  "/thirdparty/user":
+  /thirdparty/user:
     get:
       summary: Reverse-lookup third-party users given a Matrix User ID.
-      description: |-
+      description: Retrieve an array of third-party users from a Matrix User ID.
-        Retrieve an array of third-party users from a Matrix User ID.
       operationId: queryUserByID
       security:
         - accessToken: []
       parameters:
         - in: query
           name: userid
-          type: string
           description: The Matrix User ID to look up.
           required: true
-          x-example: "@bob:matrix.org"
+          example: "@bob:matrix.org"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description: |-
+          description: An array of third-party users.
-            An array of third-party users.
+          content:
+            application/json:
               schema:
                 $ref: ../application-service/definitions/user_batch.yaml
-        404:
+        "404":
           description: The Matrix User ID was not found
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND"
                   }
-          schema:
-            $ref: definitions/errors/error.yaml
       tags:
         - Third-party Lookup
+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

data/api/client-server/third_party_membership.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 Membership API for third-party identifiers"
+  title: Matrix Client-Server Room Membership API for third-party identifiers
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/invite":
     post:
@@ -71,20 +60,20 @@ paths:
 
         If a token is requested from the identity server, the homeserver will
         append a `m.room.third_party_invite` event to the room.
-
       operationId: inviteBy3PID
       security:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room identifier (not alias) to which to invite the user.
           required: true
-          x-example: "!d41d8cd:matrix.org"
+          example: "!d41d8cd:matrix.org"
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               example: {
@@ -96,7 +85,8 @@ paths:
               properties:
                 id_server:
                   type: string
-                description: The hostname+port of the identity server which should be used for third-party identifier lookups.
+                  description: The hostname+port of the identity server which should be used for
+                    third-party identifier lookups.
                 id_access_token:
                   type: string
                   description: |-
@@ -111,16 +101,23 @@ paths:
                 address:
                   type: string
                   description: The invitee's third-party identifier.
-            required: ["id_server", "id_access_token", "medium", "address"]
+              required:
+                - id_server
+                - id_access_token
+                - medium
+                - address
+        required: true
       responses:
-        200:
+        "200":
           description: The user has been invited to join the room.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object
-        403:
+              examples:
+                response:
+                  value: {}
+        "403":
           description: |-
             You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
 
@@ -128,14 +125,36 @@ paths:
             - The invitee is already a member of the room.
             - The inviter is not currently in the room.
             - The inviter's power level is insufficient to invite users to the room.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
-        429:
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "@cheeky_monkey:matrix.org is banned from the room"
+                  }
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $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

data/api/client-server/threads_list.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 Threads List API"
+  title: Matrix Client-Server Threads List API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/rooms/{roomId}/threads":
     get:
@@ -41,46 +30,49 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The room ID where the thread roots are located.
           required: true
-          x-example: "!room:example.org"
+          example: "!room:example.org"
-        - in: query
+          schema:
             type: string
+        - in: query
           name: include
-          enum: [all, participated]
           description: |-
             Optional (default `all`) flag to denote which thread roots are of interest to the caller.
             When `all`, all thread roots found in the room are returned. When `participated`, only
             thread roots for threads the user has [participated in](/client-server-api/#server-side-aggregation-of-mthread-relationships)
             will be returned.
-          x-example: "all"
+          example: all
+          schema:
+            type: string
+            enum:
+              - all
+              - participated
         - in: query
-          type: integer
           name: limit
           description: |-
             Optional limit for the maximum number of thread roots to include per response. Must be an integer
             greater than zero.
 
             Servers should apply a default value, and impose a maximum value to avoid resource exhaustion.
-          x-example: 20
+          example: 20
+          schema:
+            type: integer
         - in: query
-          type: string
           name: from
           description: |-
             A pagination token from a previous result. When not provided, the server starts paginating from
             the most recent event visible to the user (as per history visibility rules; topologically).
-          x-example: "next_batch_token"
+          example: next_batch_token
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description: |-
+          description: A portion of the available thread roots in the room, based on the
-            A portion of the available thread roots in the room, based on the filter criteria.
+            filter criteria.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "chunk": [{ "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml" }],
-              "next_batch": "next_batch_token"
-            }
               schema:
                 type: object
                 properties:
@@ -94,44 +86,78 @@ paths:
                       event is returned redacted to the caller. This is to simulate the same behaviour of a client doing
                       aggregation locally on the thread.
                     items:
-                  $ref: "definitions/client_event.yaml"
+                      $ref: definitions/client_event.yaml
                   next_batch:
                     type: string
                     description: |-
                       A token to supply to `from` to keep paginating the responses. Not present when there are
                       no further results.
-            required: [chunk]
+                required:
-        403:
+                  - chunk
-          description: |-
-            The user cannot view or peek 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 peeking.
-            - The user has been banned from the room.
-            - The room does not exist.
               examples:
-            application/json: {
+                response:
-              "errcode": "M_FORBIDDEN",
+                  value: {
-              "error": "You are not allowed to view this room."
+                    "chunk": [
+                      {
+                        "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
                       }
-          schema:
+                    ],
-            "$ref": "definitions/errors/error.yaml"
+                    "next_batch": "next_batch_token"
-        400:
+                  }
+        "400":
           description: |-
             The request was invalid in some way. A meaningful `errcode`
             and description error text will be returned. Example reasons for rejection are:
 
             - The `from` token is unknown to the server.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_INVALID_PARAM",
                     "error": "Unknown pagination token"
                   }
+        "403":
+          description: |-
+            The user cannot view or peek 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 peeking.
+            - The user has been banned from the room.
+            - The room does not exist.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
-        429:
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not allowed to view this room."
+                  }
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Threads
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/client-server/to_device.yaml

@@ -11,22 +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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Client-Server Send-to-device API"
+  title: Matrix Client-Server Send-to-device API
-  version: "1.0.0"
+  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
 paths:
   "/sendToDevice/{eventType}/{txnId}":
     put:
@@ -39,23 +27,25 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: eventType
           description: The type of event to send.
           required: true
-          x-example: "m.new_device"
+          example: m.new_device
+          schema:
+            type: string
         - in: path
           name: txnId
-          type: string
           description: |-
             The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate an
             ID unique across requests with the same access token; it will be
             used by the server to ensure idempotency of requests.
           required: true
-          x-example: "35"
+          example: "35"
-        - in: body
+          schema:
-          name: body
+            type: string
-          required: true
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               title: body
@@ -72,21 +62,37 @@ paths:
                       type: object
                       title: EventContent
                       description: Message content
-                example: {
+                  example:
-                    "@alice:example.com": {
+                    "@alice:example.com":
-                      "TLLBEANAAG": {
+                      TLLBEANAAG:
-                        "example_content_key": "value"
+                        example_content_key: value
-                      }
+              required:
-                    }
+                - messages
-                  }
+        required: true
-            required: ["messages"]
       responses:
-        200:
+        "200":
-          description:
+          description: The message was successfully sent.
-            The message was successfully sent.
+          content:
-          examples:
+            application/json:
-            application/json: {}
               schema:
                 type: object
+              examples:
+                response:
+                  value: {}
       tags:
         - Send-to-Device messaging
+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

data/api/client-server/typing.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 Typing API"
+  title: Matrix Client-Server Typing API
-  version: "1.0.0"
+  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
 paths:
   "/rooms/{roomId}/typing/{userId}":
     put:
@@ -40,21 +29,22 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: userId
           description: The user who has started to type.
           required: true
-          x-example: "@alice:example.com"
+          example: "@alice:example.com"
-        - in: path
+          schema:
             type: string
+        - in: path
           name: roomId
           description: The room in which the user is typing.
           required: true
-          x-example: "!wefh3sfukhs:example.com"
+          example: "!wefh3sfukhs:example.com"
-        - in: body
+          schema:
-          name: typingState
+            type: string
-          description: The current typing state.
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               example: {
@@ -70,18 +60,40 @@ paths:
                 timeout:
                   type: integer
                   description: The length of time in milliseconds to mark this user as typing.
-            required: ["typing"]
+              required:
+                - typing
+        description: The current typing state.
+        required: true
       responses:
-        200:
+        "200":
           description: The new typing state was set.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              }
               schema:
                 type: object  # empty json object
-        429:
+              examples:
+                response:
+                  value: {}
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Room participation
+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

data/api/client-server/users.yaml

@@ -11,23 +11,12 @@
 # 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 User Directory API"
+  title: Matrix Client-Server User Directory API
-  version: "1.0.0"
+  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
 paths:
-  "/user_directory/search":
+  /user_directory/search:
     post:
       summary: Searches the user directory.
       description: |-
@@ -44,39 +33,33 @@ paths:
       operationId: searchUserDirectory
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
             schema:
               type: object
               properties:
                 search_term:
                   type: string
                   description: The term to search for
-                example: "foo"
+                  example: foo
                 limit:
                   type: integer
                   description: The maximum number of results to return. Defaults to 10.
                   example: 10
-            required: ["search_term"]
+              required:
+                - search_term
+        required: true
       responses:
-        200:
+        "200":
           description: The results of the search.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "results": [
-                {
-                  "user_id": "@foo:bar.com",
-                  "display_name": "Foo",
-                  "avatar_url": "mxc://bar.com/foo"
-                }
-              ],
-              "limited": false
-            }
               schema:
                 type: object
-            required: ["results", "limited"]
+                required:
+                  - results
+                  - limited
                 properties:
                   results:
                     type: array
@@ -84,7 +67,8 @@ paths:
                     items:
                       title: User
                       type: object
-                  required: ["user_id"]
+                      required:
+                        - user_id
                       properties:
                         user_id:
                           type: string
@@ -92,19 +76,50 @@ paths:
                           description: The user's matrix user ID.
                         display_name:
                           type: string
-                      example: "Foo"
+                          example: Foo
                           description: The display name of the user, if one exists.
                         avatar_url:
                           type: string
                           format: uri
-                      example: "mxc://bar.com/foo"
+                          example: mxc://bar.com/foo
-                      description: The avatar url, as an [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris), if one exists.
+                          description: The avatar url, as an [`mxc://`
+                            URI](/client-server-api/#matrix-content-mxc-uris),
+                            if one exists.
                   limited:
                     type: boolean
                     description: Indicates if the result list has been truncated by the limit.
-        429:
+              examples:
+                response:
+                  value: {
+                    "results": [
+                      {
+                        "user_id": "@foo:bar.com",
+                        "display_name": "Foo",
+                        "avatar_url": "mxc://bar.com/foo"
+                      }
+                    ],
+                    "limited": false
+                  }
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - User directory
+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

data/api/client-server/versions.yaml

@@ -11,19 +11,12 @@
 # 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 Versions API"
+  title: Matrix Client-Server Versions API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client
-produces:
-  - application/json
 paths:
-  "/versions":
+  /versions:
     get:
       summary: Gets the versions of the specification supported by the server.
       description: |-
@@ -47,15 +40,10 @@ paths:
         features in their stable releases.
       operationId: getVersions
       responses:
-        200:
+        "200":
           description: The versions supported by the server.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "versions": ["r0.0.1", "v1.1"],
-                "unstable_features": {
-                  "org.example.my_feature": true
-                }
-              }
               schema:
                 type: object
                 properties:
@@ -74,6 +62,30 @@ paths:
                     additionalProperties:
                       type: boolean
                       description: Whether or not the namespaced feature is supported.
-            required: ['versions']
+                required:
+                  - versions
+              examples:
+                response:
+                  value: {
+                    "versions": [
+                      "r0.0.1",
+                      "v1.1"
+                    ],
+                    "unstable_features": {
+                      "org.example.my_feature": true
+                    }
+                  }
       tags:
         - Server administration
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client

data/api/client-server/voip.yaml

@@ -11,23 +11,12 @@
 # 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 Voice over IP API"
+  title: Matrix Client-Server Voice over IP API
-  version: "1.0.0"
+  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
 paths:
-  "/voip/turnServer":
+  /voip/turnServer:
     get:
       summary: Obtain TURN server credentials.
       description: |-
@@ -37,30 +26,19 @@ paths:
       security:
         - accessToken: []
       responses:
-        200:
+        "200":
           description: The TURN server credentials.
-          examples:
+          content:
-            application/json: {
+            application/json:
-                "username":"1443779631:@user:example.com",
-                "password":"JlKfBy1QwLrO20385QyAtEyIv0=",
-                "uris":[
-                  "turn:turn.example.com:3478?transport=udp",
-                  "turn:10.20.30.40:3478?transport=tcp",
-                  "turns:10.20.30.40:443?transport=tcp"
-                ],
-                "ttl":86400
-              }
               schema:
                 type: object
                 properties:
                   username:
                     type: string
-                description: |-
+                    description: The username to use.
-                  The username to use.
                   password:
                     type: string
-                description: |-
+                    description: The password to use.
-                  The password to use.
                   uris:
                     type: array
                     items:
@@ -69,10 +47,43 @@ paths:
                   ttl:
                     type: integer
                     description: The time-to-live in seconds
-            required: ["username", "password", "uris", "ttl"]
+                required:
-        429:
+                  - username
+                  - password
+                  - uris
+                  - ttl
+              examples:
+                response:
+                  value: {
+                    "username": "1443779631:@user:example.com",
+                    "password": "JlKfBy1QwLrO20385QyAtEyIv0=",
+                    "uris": [
+                      "turn:turn.example.com:3478?transport=udp",
+                      "turn:10.20.30.40:3478?transport=tcp",
+                      "turns:10.20.30.40:443?transport=tcp"
+                    ],
+                    "ttl": 86400
+                  }
+        "429":
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - VOIP
+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

data/api/client-server/wellknown.yaml

@@ -11,18 +11,12 @@
 # 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 Server Discovery API"
+  title: Matrix Client-Server Server Discovery API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-basePath: /.well-known
-produces:
-  - application/json
 paths:
-  "/matrix/client":
+  /matrix/client:
     get:
       summary: Gets Matrix server discovery information about the domain.
       description: |-
@@ -36,11 +30,25 @@ paths:
         but by another webserver, to be used for discovering the homeserver URL.
       operationId: getWellknown
       responses:
-        200:
+        "200":
           description: Server discovery information.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/wellknown/full.yaml"
+                $ref: definitions/wellknown/full.yaml
-        404:
+        "404":
           description: No server discovery information available.
       tags:
         - Server administration
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /.well-known

data/api/client-server/whoami.yaml

@@ -11,21 +11,12 @@
 # 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 Account Identification API"
+  title: Matrix Client-Server Account Identification API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/v3
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/account/whoami":
+  /account/whoami:
     get:
       summary: Gets information about the owner of an access token.
       description: |-
@@ -40,19 +31,15 @@ paths:
       operationId: getTokenOwner
       security:
         - accessToken: []
-      parameters: []
       responses:
-        200:
+        "200":
-          description:
+          description: The token belongs to a known user.
-            The token belongs to a known user.
+          content:
-          examples:
+            application/json:
-            application/json: {
-              "user_id": "@joe:example.org",
-              "device_id": "ABC1234"
-            }
               schema:
                 type: object
-            required: ["user_id"]
+                required:
+                  - user_id
                 properties:
                   user_id:
                     type: string
@@ -72,29 +59,57 @@ paths:
                       When `true`, the user is a [Guest User](#guest-access). When
                       not present or `false`, the user is presumed to be a non-guest
                       user.
-        401:
-          description:
-            The token is not recognised
               examples:
-            application/json: {
+                response:
+                  value: {
+                    "user_id": "@joe:example.org",
+                    "device_id": "ABC1234"
+                  }
+        "401":
+          description: The token is not recognised
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
                     "errcode": "M_UNKNOWN_TOKEN",
                     "error": "Unrecognised access token."
                   }
+        "403":
+          description: The appservice cannot masquerade as the user or has not registered
+            them.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/error.yaml"
+                $ref: definitions/errors/error.yaml
-        403:
-          description:
-            The appservice cannot masquerade as the user or has not registered them.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "Application service has not registered this user."
                   }
-          schema:
+        "429":
-            "$ref": "definitions/errors/error.yaml"
-        429:
           description: This request was rate-limited.
+          content:
+            application/json:
               schema:
-            "$ref": "definitions/errors/rate_limited.yaml"
+                $ref: definitions/errors/rate_limited.yaml
       tags:
         - Session management
+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

data/api/identity/v2_associations.yaml

@@ -12,51 +12,38 @@
 # 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 Identity Service Establishing Associations API"
+  title: Matrix Identity Service Establishing Associations API
-  version: "2.0.0"
+  version: 2.0.0
-host: localhost:8090
-schemes:
-  - https
-basePath: /_matrix/identity/v2
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/3pid/getValidated3pid":
+  /3pid/getValidated3pid:
     get:
       summary: Check whether ownership of a 3pid was validated.
-      description: |-
+      description: Determines if a given 3pid has been validated by a user.
-        Determines if a given 3pid has been validated by a user.
       operationId: getValidated3pidV2
       security:
         - accessToken: []
       parameters:
         - in: query
-          type: string
           name: sid
           description: The Session ID generated by the `requestToken` call.
           required: true
-          x-example: 1234
+          example: 1234
-        - in: query
+          schema:
             type: string
+        - in: query
           name: client_secret
           description: The client secret passed to the `requestToken` call.
           required: true
-          x-example: monkeys_are_GREAT
+          example: monkeys_are_GREAT
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: Validation information for the session.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "medium": "email",
-              "validated_at": 1457622739026,
-              "address": "louise@bobs.burgers"
-            }
               schema:
                 type: object
                 properties:
@@ -72,42 +59,61 @@ paths:
                     description: |-
                       Timestamp, in milliseconds, indicating the time that the 3pid
                       was validated.
-            required: ['medium', 'address', 'validated_at']
+                required:
-        400:
+                  - medium
+                  - address
+                  - validated_at
+              examples:
+                response:
+                  value: {
+                    "medium": "email",
+                    "validated_at": 1457622739026,
+                    "address": "louise@bobs.burgers"
+                  }
+        "400":
           description: |-
             The session has not been validated.
 
             If the session has not been validated, then `errcode` will be
             `M_SESSION_NOT_VALIDATED`.  If the session has timed out, then
             `errcode` will be `M_SESSION_EXPIRED`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_SESSION_NOT_VALIDATED",
                     "error": "This validation session has not yet been completed"
                   }
-          schema:
+        "403":
-            $ref: "../client-server/definitions/errors/error.yaml"
-        404:
-          description: The Session ID or client secret were not found.
-          examples:
-            application/json: {
-              "errcode": "M_NO_VALID_SESSION",
-              "error": "No valid session was found matching that sid and client secret"
-            }
-          schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
-        403:
           description: |
             The user must do something in order to use this endpoint. One example
             is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_TERMS_NOT_SIGNED",
                     "error": "Please accept our updated terms of service before continuing"
                   }
+        "404":
+          description: The Session ID or client secret were not found.
+          content:
+            application/json:
               schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                $ref: ../client-server/definitions/errors/error.yaml
-  "/3pid/bind":
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NO_VALID_SESSION",
+                    "error": "No valid session was found matching that sid and client secret"
+                  }
+  /3pid/bind:
     post:
       summary: Publish an association between a session and a Matrix user ID.
       description: |-
@@ -123,9 +129,9 @@ paths:
       operationId: bindV2
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
             schema:
               type: object
               example: {
@@ -143,24 +149,15 @@ paths:
                 mxid:
                   type: string
                   description: The Matrix user ID to associate with the 3pids.
-            required: ["sid", "client_secret", "mxid"]
+              required:
+                - sid
+                - client_secret
+                - mxid
       responses:
-        200:
+        "200":
           description: The association was published.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "address": "louise@bobs.burgers",
-              "medium": "email",
-              "mxid": "@ears:matrix.org",
-              "not_before": 1428825849161,
-              "not_after": 4582425849161,
-              "ts": 1428825849161,
-              "signatures": {
-                "matrix.org": {
-                  "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
-                }
-              }
-            }
               schema:
                 type: object
                 properties:
@@ -176,11 +173,13 @@ paths:
                   not_before:
                     type: integer
                     format: int64
-                description: A unix timestamp before which the association is not known to be valid.
+                    description: A unix timestamp before which the association is not known to be
+                      valid.
                   not_after:
                     type: integer
                     format: int64
-                description: A unix timestamp after which the association is not known to be valid.
+                    description: A unix timestamp after which the association is not known to be
+                      valid.
                   ts:
                     type: integer
                     format: int64
@@ -192,7 +191,7 @@ paths:
                       association should be trusted, if you trust the verifying identity
                       services.
                     allOf:
-                  - $ref: "../../schemas/server-signatures.yaml"
+                      - $ref: ../../schemas/server-signatures.yaml
                 required:
                   - address
                   - medium
@@ -201,41 +200,65 @@ paths:
                   - not_after
                   - ts
                   - signatures
-        400:
+              examples:
+                response:
+                  value: {
+                    "address": "louise@bobs.burgers",
+                    "medium": "email",
+                    "mxid": "@ears:matrix.org",
+                    "not_before": 1428825849161,
+                    "not_after": 4582425849161,
+                    "ts": 1428825849161,
+                    "signatures": {
+                      "matrix.org": {
+                        "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
+                      }
+                    }
+                  }
+        "400":
           description: |-
             The association was not published.
 
             If the session has not been validated, then `errcode` will be
             `M_SESSION_NOT_VALIDATED`.  If the session has timed out, then
             `errcode` will be `M_SESSION_EXPIRED`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_SESSION_NOT_VALIDATED",
                     "error": "This validation session has not yet been completed"
                   }
-          schema:
+        "403":
-            $ref: "../client-server/definitions/errors/error.yaml"
-        404:
-          description: The Session ID or client secret were not found
-          examples:
-            application/json: {
-              "errcode": "M_NO_VALID_SESSION",
-              "error": "No valid session was found matching that sid and client secret"
-            }
-          schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
-        403:
           description: |
             The user must do something in order to use this endpoint. One example
             is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_TERMS_NOT_SIGNED",
                     "error": "Please accept our updated terms of service before continuing"
                   }
+        "404":
+          description: The Session ID or client secret were not found
+          content:
+            application/json:
               schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                $ref: ../client-server/definitions/errors/error.yaml
-  "/3pid/unbind":
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NO_VALID_SESSION",
+                    "error": "No valid session was found matching that sid and client secret"
+                  }
+  /3pid/unbind:
     post:
       summary: Remove an association between a session and a Matrix user ID.
       description: |-
@@ -257,9 +280,9 @@ paths:
       operationId: unbindV2
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
             schema:
               type: object
               example: {
@@ -296,26 +319,28 @@ paths:
                     address:
                       type: string
                       description: The 3PID address to remove.
-                required: ['medium', 'address']
+                  required:
-            required: ["threepid", "mxid"]
+                    - medium
+                    - address
+              required:
+                - threepid
+                - mxid
       responses:
-        200:
+        "200":
           description: The association was successfully removed.
-          examples:
+          content:
-            application/json: {}
+            application/json:
               schema:
                 type: object
-        400:
+              examples:
-          description: |-
+                response:
-            If the response body is not a JSON Matrix error, the identity server
+                  value: {}
-            does not support unbinds. If a JSON Matrix error is in the response
+        "400":
-            body, the requesting party should respect the error.
-        404:
           description: |-
             If the response body is not a JSON Matrix error, the identity server
             does not support unbinds. If a JSON Matrix error is in the response
             body, the requesting party should respect the error.
-        403:
+        "403":
           description: |-
             The credentials supplied to authenticate the request were invalid.
             This may also be returned if the identity server does not support
@@ -324,15 +349,38 @@ paths:
 
             Another common error code is `M_TERMS_NOT_SIGNED` where the user
             needs to [agree to more terms](/identity-service-api/#terms-of-service) in order to continue.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "Invalid homeserver signature"
                   }
-          schema:
+        "404":
-            $ref: "../client-server/definitions/errors/error.yaml"
-        501:
           description: |-
             If the response body is not a JSON Matrix error, the identity server
             does not support unbinds. If a JSON Matrix error is in the response
             body, the requesting party should respect the error.
+        "501":
+          description: |-
+            If the response body is not a JSON Matrix error, the identity server
+            does not support unbinds. If a JSON Matrix error is in the response
+            body, the requesting party should respect the error.
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8090
+      basePath:
+        default: /_matrix/identity/v2
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/identity/v2_auth.yaml

@@ -11,22 +11,12 @@
 # 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 Identity Service Authentication API"
+  title: Matrix Identity Service Authentication API
-  version: "2.0.0"
+  version: 2.0.0
-host: localhost:8090
-schemes:
-  - https
-basePath: /_matrix/identity/v2
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/account/register":
+  /account/register:
     post:
       summary: Exchanges an OpenID token for an access token.
       description: |-
@@ -34,20 +24,18 @@ paths:
         access the identity server. The request body is the same as the values
         returned by `/openid/request_token` in the Client-Server API.
       operationId: registerAccount
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
             schema:
-            $ref: "../client-server/definitions/openid_token.yaml"
+              $ref: ../client-server/definitions/openid_token.yaml
       responses:
-        200:
+        "200":
           description: |-
             A token which can be used to authenticate future requests to the
             identity server.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "token": "abc123_OpaqueString"
-            }
               schema:
                 type: object
                 properties:
@@ -56,42 +44,54 @@ paths:
                     description: |-
                       An opaque string representing the token to authenticate future
                       requests to the identity server with.
-            required: ['token']
+                required:
-  "/account":
+                  - token
+              examples:
+                response:
+                  value: {
+                    "token": "abc123_OpaqueString"
+                  }
+  /account:
     get:
       summary: Gets account holder information for a given token.
-      description: |-
+      description: Gets information about what user owns the access token used in the
-        Gets information about what user owns the access token used in the request.
+        request.
       operationId: getAccount
       security:
         - accessToken: []
-      parameters: []
       responses:
-        200:
+        "200":
           description: The token holder's information.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "user_id": "@alice:example.org"
-            }
               schema:
                 type: object
                 properties:
                   user_id:
                     type: string
                     description: The user ID which registered the token.
-            required: ['user_id']
+                required:
-        403:
+                  - user_id
+              examples:
+                response:
+                  value: {
+                    "user_id": "@alice:example.org"
+                  }
+        "403":
           description: |
             The user must do something in order to use this endpoint. One example
             is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_TERMS_NOT_SIGNED",
                     "error": "Please accept our updated terms of service before continuing"
                   }
-          schema:
+  /account/logout:
-            $ref: "../client-server/definitions/errors/error.yaml"
-  "/account/logout":
     post:
       summary: Logs out an access token, rendering it unusable.
       description: |-
@@ -100,32 +100,54 @@ paths:
       operationId: logout
       security:
         - accessToken: []
-      parameters: []
       responses:
-        200:
+        "200":
           description: The token was successfully logged out.
-          examples:
+          content:
-            application/json: {}
+            application/json:
               schema:
                 type: object
-        401:
-          description: |-
-            The token is not registered or is otherwise unknown to the server.
               examples:
-            application/json: {
+                response:
+                  value: {}
+        "401":
+          description: The token is not registered or is otherwise unknown to the server.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
                     "errcode": "M_UNKNOWN_TOKEN",
                     "error": "Unrecognised access token"
                   }
-          schema:
+        "403":
-            $ref: "../client-server/definitions/errors/error.yaml"
-        403:
           description: |
             The user must do something in order to use this endpoint. One example
             is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_TERMS_NOT_SIGNED",
                     "error": "Please accept our updated terms of service before continuing"
                   }
-          schema:
+servers:
-            $ref: "../client-server/definitions/errors/error.yaml"
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8090
+      basePath:
+        default: /_matrix/identity/v2
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/identity/v2_email_associations.yaml

@@ -12,22 +12,12 @@
 # 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 Identity Service Email Associations API"
+  title: Matrix Identity Service Email Associations API
-  version: "2.0.0"
+  version: 2.0.0
-host: localhost:8090
-schemes:
-  - https
-basePath: /_matrix/identity/v2
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/validate/email/requestToken":
+  /validate/email/requestToken:
     post:
       summary: Request a token for validating an email address.
       description: |-
@@ -51,41 +41,49 @@ paths:
       operationId: emailRequestTokenV2
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
             schema:
-            $ref: "definitions/request_email_validation.yaml"
+              $ref: definitions/request_email_validation.yaml
       responses:
-        200:
+        "200":
           description: Session created.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/sid.yaml"
+                $ref: definitions/sid.yaml
-        400:
+        "400":
           description: |
             An error occurred.  Some possible errors are:
 
             - `M_INVALID_EMAIL`: The email address provided was invalid.
             - `M_EMAIL_SEND_ERROR`: The validation email could not be sent.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_INVALID_EMAIL",
                     "error": "The email address is not valid"
                   }
-          schema:
+        "403":
-            $ref: "../client-server/definitions/errors/error.yaml"
-        403:
           description: |
             The user must do something in order to use this endpoint. One example
             is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_TERMS_NOT_SIGNED",
                     "error": "Please accept our updated terms of service before continuing"
                   }
-          schema:
+  /validate/email/submitToken:
-            $ref: "../client-server/definitions/errors/error.yaml"
-  "/validate/email/submitToken":
     post:
       summary: Validate ownership of an email address.
       description: |-
@@ -110,9 +108,9 @@ paths:
       operationId: emailSubmitTokenPostV2
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
             schema:
               type: object
               example: {
@@ -129,34 +127,44 @@ paths:
                   description: The client secret that was supplied to the `requestToken` call.
                 token:
                   type: string
-                description: The token generated by the `requestToken` call and emailed to the user.
+                  description: The token generated by the `requestToken` call and emailed to the
-            required: ["sid", "client_secret", "token"]
+                    user.
+              required:
+                - sid
+                - client_secret
+                - token
       responses:
-        200:
+        "200":
-          description:
+          description: The success of the validation.
-            The success of the validation.
+          content:
-          examples:
+            application/json:
-            application/json: {
-              "success": true
-            }
               schema:
                 type: object
                 properties:
                   success:
                     type: boolean
                     description: Whether the validation was successful or not.
-            required: ['success']
+                required:
-        403:
+                  - success
+              examples:
+                response:
+                  value: {
+                    "success": true
+                  }
+        "403":
           description: |
             The user must do something in order to use this endpoint. One example
             is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_TERMS_NOT_SIGNED",
                     "error": "Please accept our updated terms of service before continuing"
                   }
-          schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
     get:
       summary: Validate ownership of an email address.
       description: |-
@@ -175,42 +183,63 @@ paths:
         - accessToken: []
       parameters:
         - in: query
-          type: string
           name: sid
           required: true
           description: The session ID, generated by the `requestToken` call.
-          x-example: 1234
+          example: 1234
-        - in: query
+          schema:
             type: string
+        - in: query
           name: client_secret
           required: true
           description: The client secret that was supplied to the `requestToken` call.
-          x-example: monkeys_are_GREAT
+          example: monkeys_are_GREAT
-        - in: query
+          schema:
             type: string
+        - in: query
           name: token
           required: true
-          description: The token generated by the `requestToken` call and emailed to the user.
+          description: The token generated by the `requestToken` call and emailed to the
-          x-example: atoken
+            user.
+          example: atoken
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: Email address is validated.
-        "3xx":
+        "403":
-          description: |-
-            Email address is validated, and the `next_link` parameter was
-            provided to the `requestToken` call.  The user must be redirected
-            to the URL provided by the `next_link` parameter.
-        "4xx":
-          description:
-            Validation failed.
-        403:
           description: |
             The user must do something in order to use this endpoint. One example
             is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_TERMS_NOT_SIGNED",
                     "error": "Please accept our updated terms of service before continuing"
                   }
-          schema:
+        "3XX":
-            $ref: "../client-server/definitions/errors/error.yaml"
+          description: |-
+            Email address is validated, and the `next_link` parameter was
+            provided to the `requestToken` call.  The user must be redirected
+            to the URL provided by the `next_link` parameter.
+        "4XX":
+          description: Validation failed.
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8090
+      basePath:
+        default: /_matrix/identity/v2
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/identity/v2_invitation_signing.yaml

@@ -12,22 +12,12 @@
 # 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 Identity Service Ephemeral Invitation Signing API"
+  title: Matrix Identity Service Ephemeral Invitation Signing API
-  version: "2.0.0"
+  version: 2.0.0
-host: localhost:8090
-schemes:
-  - https
-basePath: /_matrix/identity/v2
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/sign-ed25519":
+  /sign-ed25519:
     post:
       summary: Sign invitation details
       description: |-
@@ -38,9 +28,9 @@ paths:
       operationId: blindlySignStuffV2
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
             schema:
               type: object
               example: {
@@ -57,11 +47,17 @@ paths:
                   description: The token from the call to `store-invite`.
                 private_key:
                   type: string
-                description: The private key, encoded as [Unpadded base64](/appendices/#unpadded-base64).
+                  description: The private key, encoded as [Unpadded
-            required: ["mxid", "token", "private_key"]
+                    base64](/appendices/#unpadded-base64).
+              required:
+                - mxid
+                - token
+                - private_key
       responses:
-        200:
+        "200":
           description: The signed JSON of the mxid, sender, and token.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -75,13 +71,18 @@ paths:
                     type: object
                     description: The signature of the mxid, sender, and token.
                     allOf:
-                  - $ref: "../../schemas/server-signatures.yaml"
+                      - $ref: ../../schemas/server-signatures.yaml
                   token:
                     type: string
                     description: The token for the invitation.
-            required: ['mxid', 'sender', 'signatures', 'token']
+                required:
+                  - mxid
+                  - sender
+                  - signatures
+                  - token
               examples:
-            application/json: {
+                response:
+                  value: {
                     "mxid": "@foo:bar.com",
                     "sender": "@baz:bar.com",
                     "signatures": {
@@ -91,23 +92,44 @@ paths:
                     },
                     "token": "abc123"
                   }
-        404:
+        "403":
-          description: The token was not found.
-          examples:
-            application/json: {
-              "errcode": "M_UNRECOGNIZED",
-              "error": "Didn't recognize token"
-            }
-          schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
-        403:
           description: |
             The user must do something in order to use this endpoint. One example
             is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_TERMS_NOT_SIGNED",
                     "error": "Please accept our updated terms of service before continuing"
                   }
+        "404":
+          description: The token was not found.
+          content:
+            application/json:
               schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_UNRECOGNIZED",
+                    "error": "Didn't recognize token"
+                  }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8090
+      basePath:
+        default: /_matrix/identity/v2
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/identity/v2_lookup.yaml

@@ -15,22 +15,12 @@
 # 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 Identity Service Lookup API"
+  title: Matrix Identity Service Lookup API
-  version: "2.0.0"
+  version: 2.0.0
-host: localhost:8090
-schemes:
-  - https
-basePath: /_matrix/identity/v2
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/hash_details":
+  /hash_details:
     get:
       summary: Gets hash function information from the server.
       description: |-
@@ -39,15 +29,11 @@ paths:
       operationId: getHashDetails
       security:
         - accessToken: []
-      parameters: []
       responses:
-        200:
+        "200":
           description: The hash function information.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "lookup_pepper": "matrixrocks",
-              "algorithms": ["none", "sha256"]
-            }
               schema:
                 type: object
                 properties:
@@ -62,10 +48,20 @@ paths:
                     type: array
                     items:
                       type: string
-                description: |-
+                    description: The algorithms the server supports. Must contain at least `sha256`.
-                  The algorithms the server supports. Must contain at least `sha256`.
+                required:
-            required: ['lookup_pepper', 'algorithms']
+                  - lookup_pepper
-  "/lookup":
+                  - algorithms
+              examples:
+                response:
+                  value: {
+                    "lookup_pepper": "matrixrocks",
+                    "algorithms": [
+                      "none",
+                      "sha256"
+                    ]
+                  }
+  /lookup:
     post:
       summary: Look up Matrix User IDs for a set of 3PIDs.
       description: |-
@@ -75,9 +71,9 @@ paths:
       operationId: lookupUsersV2
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
             schema:
               type: object
               properties:
@@ -86,13 +82,13 @@ paths:
                   description: |-
                     The algorithm the client is using to encode the `addresses`. This
                     should be one of the available options from `/hash_details`.
-                example: "sha256"
+                  example: sha256
                 pepper:
                   type: string
                   description: |-
                     The pepper from `/hash_details`. This is required even when the
                     `algorithm` does not make use of it.
-                example: "matrixrocks"
+                  example: matrixrocks
                 addresses:
                   type: array
                   items:
@@ -105,21 +101,18 @@ paths:
                     Note that addresses are case sensitive: review the
                     [3PID Types](/appendices#3pid-types) to verify the intended case an
                     identifier should be prior to submission/hashing.
-                example: [
+                  example:
-                  "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc",
+                    - 4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc
-                  "nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I"
+                    - nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I
-                ]
+              required:
-            required: ['algorithm', 'pepper', 'addresses']
+                - algorithm
+                - pepper
+                - addresses
       responses:
-        200:
+        "200":
-          description:
+          description: The associations for any matched `addresses`.
-            The associations for any matched `addresses`.
+          content:
-          examples:
+            application/json:
-            application/json: {
-              "mappings": {
-                "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
-              }
-            }
               schema:
                 type: object
                 properties:
@@ -132,21 +125,41 @@ paths:
                     title: AssociatedMappings
                     additionalProperties:
                       type: string
-            required: ['mappings']
+                required:
-        400:
+                  - mappings
-          description:
-            The client's request was invalid in some way. One possible problem could
-            be the `pepper` being invalid after the server has rotated it - this is
-            presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make
-            a call to `/hash_details` to get a new pepper in this scenario, being
-            careful to avoid retry loops.
-
-            `M_INVALID_PARAM` can also be returned to indicate the client supplied
-            an `algorithm` that is unknown to the server.
               examples:
-            application/json: {
+                response:
+                  value: {
+                    "mappings": {
+                      "4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
+                    }
+                  }
+        "400":
+          description: |-
+            The client's request was invalid in some way. One possible problem could be the `pepper` being invalid after the server has rotated it - this is presented with the `M_INVALID_PEPPER` error code. Clients SHOULD make a call to `/hash_details` to get a new pepper in this scenario, being careful to avoid retry loops.
+            `M_INVALID_PARAM` can also be returned to indicate the client supplied an `algorithm` that is unknown to the server.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
                     "errcode": "M_INVALID_PEPPER",
                     "error": "Unknown or invalid pepper - has it been rotated?"
                   }
-          schema:
+servers:
-            $ref: "../client-server/definitions/errors/error.yaml"
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8090
+      basePath:
+        default: /_matrix/identity/v2
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/identity/v2_phone_associations.yaml

@@ -12,22 +12,12 @@
 # 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 Identity Service Phone Number Associations API"
+  title: Matrix Identity Service Phone Number Associations API
-  version: "2.0.0"
+  version: 2.0.0
-host: localhost:8090
-schemes:
-  - https
-basePath: /_matrix/identity/v2
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/validate/msisdn/requestToken":
+  /validate/msisdn/requestToken:
     post:
       summary: Request a token for validating a phone number.
       description: |-
@@ -51,17 +41,19 @@ paths:
       operationId: msisdnRequestTokenV2
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
             schema:
-            $ref: "definitions/request_msisdn_validation.yaml"
+              $ref: definitions/request_msisdn_validation.yaml
       responses:
-        200:
+        "200":
           description: Session created.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/sid.yaml"
+                $ref: definitions/sid.yaml
-        400:
+        "400":
           description: |
             An error occurred. Some possible errors are:
 
@@ -69,25 +61,31 @@ paths:
             - `M_SEND_ERROR`: The validation SMS could not be sent.
             - `M_DESTINATION_REJECTED`: The identity server cannot deliver an
               SMS to the provided country or region.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_INVALID_ADDRESS",
                     "error": "The phone number is not valid"
                   }
-          schema:
+        "403":
-            $ref: "../client-server/definitions/errors/error.yaml"
-        403:
           description: |
             The user must do something in order to use this endpoint. One example
             is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_TERMS_NOT_SIGNED",
                     "error": "Please accept our updated terms of service before continuing"
                   }
-          schema:
+  /validate/msisdn/submitToken:
-            $ref: "../client-server/definitions/errors/error.yaml"
-  "/validate/msisdn/submitToken":
     post:
       summary: Validate ownership of a phone number.
       description: |-
@@ -112,9 +110,9 @@ paths:
       operationId: msisdnSubmitTokenPostV2
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
             schema:
               type: object
               example: {
@@ -131,34 +129,44 @@ paths:
                   description: The client secret that was supplied to the `requestToken` call.
                 token:
                   type: string
-                description: The token generated by the `requestToken` call and sent to the user.
+                  description: The token generated by the `requestToken` call and sent to the
-            required: ["sid", "client_secret", "token"]
+                    user.
+              required:
+                - sid
+                - client_secret
+                - token
       responses:
-        200:
+        "200":
-          description:
+          description: The success of the validation.
-            The success of the validation.
+          content:
-          examples:
+            application/json:
-            application/json: {
-              "success": true
-            }
               schema:
                 type: object
                 properties:
                   success:
                     type: boolean
                     description: Whether the validation was successful or not.
-            required: ['success']
+                required:
-        403:
+                  - success
+              examples:
+                response:
+                  value: {
+                    "success": true
+                  }
+        "403":
           description: |
             The user must do something in order to use this endpoint. One example
             is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_TERMS_NOT_SIGNED",
                     "error": "Please accept our updated terms of service before continuing"
                   }
-          schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
     get:
       summary: Validate ownership of a phone number.
       description: |-
@@ -177,42 +185,62 @@ paths:
         - accessToken: []
       parameters:
         - in: query
-          type: string
           name: sid
           required: true
           description: The session ID, generated by the `requestToken` call.
-          x-example: 1234
+          example: 1234
-        - in: query
+          schema:
             type: string
+        - in: query
           name: client_secret
           required: true
           description: The client secret that was supplied to the `requestToken` call.
-          x-example: monkeys_are_GREAT
+          example: monkeys_are_GREAT
-        - in: query
+          schema:
             type: string
+        - in: query
           name: token
           required: true
           description: The token generated by the `requestToken` call and sent to the user.
-          x-example: atoken
+          example: atoken
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: Phone number is validated.
-        "3xx":
+        "403":
-          description: |-
-            Phone number address is validated, and the `next_link` parameter
-            was provided to the `requestToken` call. The user must be
-            redirected to the URL provided by the `next_link` parameter.
-        "4xx":
-          description:
-            Validation failed.
-        403:
           description: |
             The user must do something in order to use this endpoint. One example
             is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_TERMS_NOT_SIGNED",
                     "error": "Please accept our updated terms of service before continuing"
                   }
-          schema:
+        "3XX":
-            $ref: "../client-server/definitions/errors/error.yaml"
+          description: |-
+            Phone number address is validated, and the `next_link` parameter
+            was provided to the `requestToken` call. The user must be
+            redirected to the URL provided by the `next_link` parameter.
+        "4XX":
+          description: Validation failed.
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8090
+      basePath:
+        default: /_matrix/identity/v2
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/identity/v2_ping.yaml

@@ -13,19 +13,12 @@
 # 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.
-
+openapi: 3.1.0
-swagger: "2.0"
 info:
-  title: "Matrix Identity Service Ping API"
+  title: Matrix Identity Service Ping API
-  version: "2.0.0"
+  version: 2.0.0
-host: localhost:8090
-schemes:
-  - https
-basePath: /_matrix/identity
-produces:
-  - application/json
 paths:
-  "/v2":
+  /v2:
     get:
       summary: Checks that an identity server is available at this API endpoint.
       description: |-
@@ -38,9 +31,24 @@ paths:
         by entities acting as a client for the identity server.
       operationId: pingV2
       responses:
-        200:
+        "200":
           description: An identity server is ready to serve requests.
-          examples:
+          content:
-            application/json: {}
+            application/json:
               schema:
                 type: object
+              examples:
+                response:
+                  value: {}
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8090
+      basePath:
+        default: /_matrix/identity

data/api/identity/v2_pubkey.yaml

@@ -12,61 +12,58 @@
 # 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 Identity Service Public Key API"
+  title: Matrix Identity Service Public Key API
-  version: "2.0.0"
+  version: 2.0.0
-host: localhost:8090
-schemes:
-  - https
-basePath: /_matrix/identity/v2
-consumes:
-  - application/json
-produces:
-  - application/json
 paths:
   "/pubkey/{keyId}":
     get:
       summary: Get a public key.
-      description: |-
+      description: Get the public key for the passed key ID.
-        Get the public key for the passed key ID.
       operationId: getPubKeyV2
       parameters:
         - in: path
-          type: string
           name: keyId
           required: true
           description: |-
             The ID of the key. This should take the form algorithm:identifier
             where algorithm identifies the signing algorithm, and the identifier
             is an opaque string.
-          x-example: "ed25519:0"
+          example: ed25519:0
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description:
+          description: The public key exists.
-            The public key exists.
+          content:
-          examples:
+            application/json:
-            application/json: {
-              "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
-            }
               schema:
                 type: object
                 properties:
                   public_key:
                     type: string
                     description: Unpadded Base64 encoded public key.
-            required: ['public_key']
+                required:
-        404:
+                  - public_key
-          description:
+              examples:
-            The public key was not found.
+                response:
+                  value: {
+                    "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
+                  }
+        "404":
+          description: The public key was not found.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "The public key was not found"
                   }
-          schema:
+  /pubkey/isvalid:
-            $ref: "../client-server/definitions/errors/error.yaml"
-  "/pubkey/isvalid":
     get:
       summary: Check whether a long-term public key is valid.
       description: |-
@@ -75,53 +72,70 @@ paths:
       operationId: isPubKeyValidV2
       parameters:
         - in: query
-          type: string
           name: public_key
           required: true
-          description: |-
+          description: The unpadded base64-encoded public key to check.
-            The unpadded base64-encoded public key to check.
+          example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
-          x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description:
+          description: The validity of the public key.
-            The validity of the public key.
+          content:
-          examples:
+            application/json:
-            application/json: {
-              "valid": true
-            }
               schema:
                 type: object
                 properties:
                   valid:
                     type: boolean
                     description: Whether the public key is recognised and is currently valid.
-            required: ['valid']
+                required:
-  "/pubkey/ephemeral/isvalid":
+                  - valid
+              examples:
+                response:
+                  value: {
+                    "valid": true
+                  }
+  /pubkey/ephemeral/isvalid:
     get:
       summary: Check whether a short-term public key is valid.
-      description: |-
+      description: Check whether a short-term public key is valid.
-        Check whether a short-term public key is valid.
       operationId: isEphemeralPubKeyValidV2
       parameters:
         - in: query
-          type: string
           name: public_key
           required: true
-          description: |-
+          description: The unpadded base64-encoded public key to check.
-            The unpadded base64-encoded public key to check.
+          example: VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c
-          x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description:
+          description: The validity of the public key.
-            The validity of the public key.
+          content:
-          examples:
+            application/json:
-            application/json: {
-              "valid": true
-            }
               schema:
                 type: object
                 properties:
                   valid:
                     type: boolean
                     description: Whether the public key is recognised and is currently valid.
-            required: ['valid']
+                required:
+                  - valid
+              examples:
+                response:
+                  value: {
+                    "valid": true
+                  }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8090
+      basePath:
+        default: /_matrix/identity/v2

data/api/identity/v2_store_invite.yaml

@@ -12,22 +12,12 @@
 # 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 Identity Service Store Invitations API"
+  title: Matrix Identity Service Store Invitations API
-  version: "2.0.0"
+  version: 2.0.0
-host: localhost:8090
-schemes:
-  - https
-basePath: /_matrix/identity/v2
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/store-invite":
+  /store-invite:
     post:
       summary: Store pending invitations to a user's 3pid.
       description: |-
@@ -62,20 +52,20 @@ paths:
       operationId: storeInviteV2
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
             schema:
               type: object
               properties:
                 medium:
                   type: string
                   description: The literal string `email`.
-                example: "email"
+                  example: email
                 address:
                   type: string
                   description: The email address of the invited user.
-                example: "foo@example.com"
+                  example: foo@example.com
                 room_id:
                   type: string
                   description: The Matrix room ID to which the user is invited
@@ -96,37 +86,44 @@ paths:
                   description: |-
                     The Content URI for the room to which the user is invited. This should
                     be retrieved from the `m.room.avatar` state event.
-                example: "mxc://example.org/s0meM3dia"
+                  example: mxc://example.org/s0meM3dia
                 room_join_rules:
                   type: string
                   description: |-
                     The `join_rule` for the room to which the user is invited. This should
                     be retrieved from the `m.room.join_rules` state event.
-                example: "public"
+                  example: public
                 room_name:
                   type: string
                   description: |-
                     The name of the room to which the user is invited. This should be retrieved
                     from the `m.room.name` state event.
-                example: "Bob's Emporium of Messages"
+                  example: Bob's Emporium of Messages
                 sender_display_name:
                   type: string
                   description: The display name of the user ID initiating the invite.
-                example: "Bob Smith"
+                  example: Bob Smith
                 sender_avatar_url:
                   type: string
-                description: The Content URI for the avatar of the user ID initiating the invite.
+                  description: The Content URI for the avatar of the user ID initiating the
-                example: "mxc://example.org/an0th3rM3dia"
+                    invite.
+                  example: mxc://example.org/an0th3rM3dia
                 room_type:
                   type: string
                   description: |-
                     The `type` from the `m.room.create` event's `content`. If the create event doesn't
                     have a specified `type`, this field is not included.
-                example: "m.space"
+                  example: m.space
-            required: ["medium", "address", "room_id", "sender"]
+              required:
+                - medium
+                - address
+                - room_id
+                - sender
       responses:
-        200:
+        "200":
           description: The invitation was stored.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -155,13 +152,19 @@ paths:
                             The URI of an endpoint where the validity of this key can be checked
                             by passing it as a `public_key` query parameter. See
                             [key management](/identity-service-api/#key-management).
-                  required: ['public_key', 'key_validity_url']
+                      required:
+                        - public_key
+                        - key_validity_url
                   display_name:
                     type: string
                     description: The generated (redacted) display name.
-            required: ['token', 'public_keys', 'display_name']
+                required:
+                  - token
+                  - public_keys
+                  - display_name
               examples:
-            application/json: {
+                response:
+                  value: {
                     "token": "sometoken",
                     "public_keys": [
                       {
@@ -175,29 +178,50 @@ paths:
                     ],
                     "display_name": "f...@b..."
                   }
-        400:
+        "400":
           description: |
             An error has occurred.
 
             If the 3pid is already bound to a Matrix user ID, the error code
             will be `M_THREEPID_IN_USE`.  If the medium is unsupported, the
             error code will be `M_UNRECOGNIZED`.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_THREEPID_IN_USE",
                     "error": "Binding already known",
                     "mxid": "@alice:example.com"
                   }
-          schema:
+        "403":
-            $ref: "../client-server/definitions/errors/error.yaml"
-        403:
           description: |
             The user must do something in order to use this endpoint. One example
             is an `M_TERMS_NOT_SIGNED` error where the user must [agree to more terms](/identity-service-api/#terms-of-service).
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_TERMS_NOT_SIGNED",
                     "error": "Please accept our updated terms of service before continuing"
                   }
-          schema:
+servers:
-            $ref: "../client-server/definitions/errors/error.yaml"
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8090
+      basePath:
+        default: /_matrix/identity/v2
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/identity/v2_terms.yaml

@@ -11,22 +11,12 @@
 # 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 Identity Service Terms of Service API"
+  title: Matrix Identity Service Terms of Service API
-  version: "2.0.0"
+  version: 2.0.0
-host: localhost:8090
-schemes:
-  - https
-basePath: /_matrix/identity/v2
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/terms":
+  /terms:
     get:
       summary: Gets the terms of service offered by the server.
       description: |-
@@ -34,38 +24,11 @@ paths:
         to filter through the terms to determine which terms need acceptance from the
         user. Note that this endpoint does not require authentication.
       operationId: getTerms
-      parameters: []
       responses:
-        200:
+        "200":
-          description: |-
+          description: The terms of service offered by the server.
-            The terms of service offered by the server.
+          content:
-          examples:
+            application/json:
-            application/json: {
-              "policies": {
-                "terms_of_service": {
-                  "version": "2.0",
-                  "en": {
-                    "name": "Terms of Service",
-                    "url": "https://example.org/somewhere/terms-2.0-en.html"
-                  },
-                  "fr": {
-                    "name": "Conditions d'utilisation",
-                    "url": "https://example.org/somewhere/terms-2.0-fr.html"
-                  }
-                },
-                "privacy_policy": {
-                  "version": "1.2",
-                  "en": {
-                    "name": "Privacy Policy",
-                    "url": "https://example.org/somewhere/privacy-1.2-en.html"
-                  },
-                  "fr": {
-                    "name": "Politique de confidentialité",
-                    "url": "https://example.org/somewhere/privacy-1.2-fr.html"
-                  }
-                }
-              }
-            }
               schema:
                 type: object
                 properties:
@@ -87,13 +50,13 @@ paths:
                           description: |-
                             The version for the policy. There are no requirements on what this
                             might be and could be "alpha", semantically versioned, or arbitrary.
-                  required: ['version']
+                      required:
+                        - version
                       # TODO: TravisR - Make this render
                       additionalProperties:
                         type: object
                         title: Internationalised Policy
-                    description: |-
+                        description: The policy information for the specified language.
-                      The policy information for the specified language.
                         properties:
                           name:
                             type: string
@@ -107,8 +70,39 @@ paths:
                               in the future: for example, if this was "https://example.org/terms.html"
                               then the server would be unable to update it because the client would
                               have already added that URL to the `m.accepted_terms` collection.
-                    required: ['name', 'url']
+                        required:
-            required: ['policies']
+                          - name
+                          - url
+                required:
+                  - policies
+              examples:
+                response:
+                  value: {
+                    "policies": {
+                      "terms_of_service": {
+                        "version": "2.0",
+                        "en": {
+                          "name": "Terms of Service",
+                          "url": "https://example.org/somewhere/terms-2.0-en.html"
+                        },
+                        "fr": {
+                          "name": "Conditions d'utilisation",
+                          "url": "https://example.org/somewhere/terms-2.0-fr.html"
+                        }
+                      },
+                      "privacy_policy": {
+                        "version": "1.2",
+                        "en": {
+                          "name": "Privacy Policy",
+                          "url": "https://example.org/somewhere/privacy-1.2-en.html"
+                        },
+                        "fr": {
+                          "name": "Politique de confidentialité",
+                          "url": "https://example.org/somewhere/privacy-1.2-fr.html"
+                        }
+                      }
+                    }
+                  }
     post:
       summary: Indicates acceptance of terms to the server.
       description: |-
@@ -126,9 +120,9 @@ paths:
       operationId: agreeToTerms
       security:
         - accessToken: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
             schema:
               type: object
               properties:
@@ -137,13 +131,32 @@ paths:
                   items:
                     type: string
                   description: The URLs the user is accepting in this request.
-                example: "https://example.org/somewhere/terms-2.0-en.html"
+                  example: https://example.org/somewhere/terms-2.0-en.html
-            required: ['user_accepts']
+              required:
+                - user_accepts
       responses:
-        200:
+        "200":
-          description: |-
+          description: The server has considered the user as having accepted the provided
-            The server has considered the user as having accepted the provided URLs.
+            URLs.
-          examples:
+          content:
-            application/json: {}
+            application/json:
               schema:
                 type: object
+              examples:
+                response:
+                  value: {}
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8090
+      basePath:
+        default: /_matrix/identity/v2
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/identity/versions.yaml

@@ -11,18 +11,12 @@
 # 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 Identity Service Versions API"
+  title: Matrix Identity Service Versions API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8090
-schemes:
-  - https
-basePath: /_matrix/identity
-produces:
-  - application/json
 paths:
-  "/versions":
+  /versions:
     get:
       x-addedInMatrixVersion: "1.1"
       summary: Gets the versions of the specification supported by the server.
@@ -36,12 +30,10 @@ paths:
         All supported versions, including patch versions, are reported by the server.
       operationId: getVersions
       responses:
-        200:
+        "200":
           description: The versions supported by the server.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "versions": ["r0.2.0", "r0.2.1", "v1.1"]
-            }
               schema:
                 type: object
                 properties:
@@ -51,4 +43,26 @@ paths:
                     items:
                       type: string
                       description: The supported versions.
-            required: ['versions']
+                required:
+                  - versions
+              examples:
+                response:
+                  value: {
+                    "versions": [
+                      "r0.2.0",
+                      "r0.2.1",
+                      "v1.1"
+                    ]
+                  }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8090
+      basePath:
+        default: /_matrix/identity

data/api/push-gateway/push_notifier.yaml

@@ -12,21 +12,12 @@
 # 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 Push Notification API"
+  title: Matrix Push Notification API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/push/v1
-consumes:
-  - application/json
-produces:
-  - application/json
 paths:
-  "/notify":
+  /notify:
     post:
       summary: Notify a push gateway about an event.
       description: |-
@@ -48,11 +39,9 @@ paths:
         This means that the HTTP path may be different depending on the push
         gateway.
       operationId: notify
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: notification
+          application/json:
-          description: Information about the push notification.
-          required: true
             schema:
               type: object
               example: {
@@ -70,7 +59,7 @@ paths:
                     "body": "I'm floating in a most peculiar way."
                   },
                   "counts": {
-                  "unread" : 2,
+                    "unread": 2,
                     "missed_calls": 1
                   },
                   "devices": [
@@ -78,7 +67,7 @@ paths:
                       "app_id": "org.matrix.matrixConsole.ios",
                       "pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/",
                       "pushkey_ts": 12345678,
-                    "data" : {},
+                      "data": {},
                       "tweaks": {
                         "sound": "bing"
                       }
@@ -86,13 +75,15 @@ paths:
                   ]
                 }
               }
-            required: ["notification"]
+              required:
+                - notification
               properties:
                 notification:
                   type: object
                   title: Notification
                   description: Information about the push notification
-                required: ["devices"]
+                  required:
+                    - devices
                   properties:
                     event_id:
                       type: string
@@ -110,12 +101,10 @@ paths:
                         Matrix event.
                     type:
                       type: string
-                    description: |-
+                      description: The type of the event as in the event's `type` field.
-                      The type of the event as in the event's `type` field.
                     sender:
                       type: string
-                    description: |-
+                      description: The sender of the event as in the corresponding event field.
-                      The sender of the event as in the corresponding event field.
                     sender_display_name:
                       type: string
                       description: |-
@@ -135,7 +124,9 @@ paths:
                         member event is equal to the user's Matrix ID).
                     prio:
                       type: string
-                    enum: ["high", "low"]
+                      enum:
+                        - high
+                        - low
                       description: |-
                         The priority of the notification. If omitted, `high` is
                         assumed. This may be used by push gateways to deliver less
@@ -169,16 +160,15 @@ paths:
                     devices:
                       type: array
                       title: Devices
-                    description: |-
+                      description: This is an array of devices that the notification should be sent
-                      This is an array of devices that the notification should be sent to.
+                        to.
                       items:
                         type: object
                         title: Device
                         properties:
                           app_id:
                             type: string
-                          description: |-
+                            description: The `app_id` given when the pusher was created.
-                            The `app_id` given when the pusher was created.
                           pushkey:
                             type: string
                             description: The `pushkey` given when the pusher was created.
@@ -201,14 +191,16 @@ paths:
                             description: |-
                               A dictionary of customisations made to the way this
                               notification is to be presented. These are added by push rules.
-                      required: ['app_id', 'pushkey']
+                        required:
+                          - app_id
+                          - pushkey
+        description: Information about the push notification.
+        required: true
       responses:
-        200:
+        "200":
           description: A list of rejected push keys.
-          examples:
+          content:
-            application/json: {
+            application/json:
-              "rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ]
-            }
               schema:
                 type: object  # empty json object
                 properties:
@@ -226,4 +218,24 @@ paths:
                     items:
                       type: string
                       description: A pushkey that has been rejected.
-            required: ['rejected']
+                required:
+                  - rejected
+              examples:
+                response:
+                  value: {
+                    "rejected": [
+                      "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/"
+                    ]
+                  }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/push/v1

data/api/server-server/backfill.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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation Events API"
+  title: Matrix Federation Events API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/backfill/{roomId}":
     get:
@@ -40,26 +29,30 @@ paths:
       parameters:
         - in: path
           name: roomId
-          type: string
           description: The room ID to backfill.
           required: true
-          x-example: "!SomeRoom:matrix.org"
+          example: "!SomeRoom:matrix.org"
+          schema:
+            type: string
         - in: query
           name: v
+          description: The event IDs to backfill from.
+          required: true
+          example:
+            - $abc123:matrix.org
+          schema:
             type: array
             items:
               type: string
-          description: The event IDs to backfill from.
-          required: true
-          x-example: ["$abc123:matrix.org"]
         - in: query
           name: limit
-          type: integer
           description: The maximum number of PDUs to retrieve, including the given events.
           required: true
-          x-example: 2
+          example: 2
+          schema:
+            type: integer
       responses:
-        200:
+        "200":
           description: |-
             A transaction containing the PDUs that preceded the given event(s), including the given
             event(s), up to the given limit.
@@ -71,8 +64,10 @@ paths:
             Due to historical reasons, it is possible that events which were previously accepted
             would now be rejected by these limitations. The events should be rejected per usual by
             the `/send`, `/get_missing_events`, and remaining endpoints.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/unlimited_pdu_transaction.yaml"
+                $ref: definitions/unlimited_pdu_transaction.yaml
   "/get_missing_events/{roomId}":
     post:
       summary: Retrieves events that the sender is missing
@@ -86,12 +81,14 @@ paths:
       parameters:
         - in: path
           name: roomId
-          type: string
           description: The room ID to search in.
           required: true
-          x-example: "!SomeRoom:matrix.org"
+          example: "!SomeRoom:matrix.org"
-        - in: body
+          schema:
-          name: body
+            type: string
+      requestBody:
+        content:
+          application/json:
             schema:
               type: object
               properties:
@@ -110,19 +107,25 @@ paths:
                     the previous events of `latest_events`.
                   items:
                     type: string
-                example: ["$missing_event:example.org"]
+                  example:
+                    - $missing_event:example.org
                 latest_events:
                   type: array
                   description: The event IDs to retrieve the previous events for.
                   items:
                     type: string
-                example: ["$event_that_has_the_missing_event_as_a_previous_event:example.org"]
+                  example:
-            required: ['earliest_events', 'latest_events']
+                    - $event_that_has_the_missing_event_as_a_previous_event:example.org
+              required:
+                - earliest_events
+                - latest_events
       responses:
-        200:
+        "200":
           description: |-
             The previous events for `latest_events`, excluding any `earliest_events`, up to the
             provided `limit`.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -134,10 +137,29 @@ paths:
                     items:
                       type: object
                       title: PDU
-            required: ['events']
+                required:
+                  - events
               examples:
-            application/json: {
+                response:
+                  value: {
                     "events": [
-                {"$ref": "examples/minimal_pdu.json"}
+                      {
+                        "$ref": "examples/minimal_pdu.json"
+                      }
                     ]
                   }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/federation/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/server-server/definitions/unsigned_pdu_base.yaml

@@ -56,6 +56,7 @@ properties:
       maxItems: 2
       minItems: 2
       items:
+        anyOf:
           - type: string
             title: Event ID
             example: "$abc123:matrix.org"
@@ -91,6 +92,7 @@ properties:
       maxItems: 2
       minItems: 2
       items:
+        anyOf:
           - type: string
             title: Event ID
             example: "$abc123:matrix.org"

data/api/server-server/event_auth.yaml

@@ -11,46 +11,38 @@
 # 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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation Event Authorization API"
+  title: Matrix Federation Event Authorization API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/event_auth/{roomId}/{eventId}":
     get:
       summary: Get the auth chain for a given event
-      description: |-
+      description: Retrieves the complete auth chain for a given event.
-        Retrieves the complete auth chain for a given event.
       operationId: getEventAuth
       security:
         - signedRequest: []
       parameters:
         - in: path
           name: roomId
-          type: string
           description: The room ID to get the auth chain for.
           required: true
-          x-example: "!abc123:matrix.org"
+          example: "!abc123:matrix.org"
+          schema:
+            type: string
         - in: path
           name: eventId
-          type: string
           description: The event ID to get the auth chain of.
           required: true
-          x-example: "$helloworld:example.org"
+          example: $helloworld:example.org
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The auth chain for the event.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -66,5 +58,21 @@ paths:
                       title: PDU
                       properties: {}
                       example:
-                    $ref: "examples/minimal_pdu.json"
+                        $ref: examples/minimal_pdu.json
-            required: ['auth_chain']
+                required:
+                  - auth_chain
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/federation/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/server-server/events.yaml

@@ -11,47 +11,41 @@
 # 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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation Events API"
+  title: Matrix Federation Events API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v1
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/state/{roomId}":
     get:
       summary: Get all the state of a given room
-      description: |-
+      description: Retrieves a snapshot of a room's state at a given event.
-        Retrieves a snapshot of a room's state at a given event.
       operationId: getRoomState
       security:
         - signedRequest: []
       parameters:
         - in: path
           name: roomId
-          type: string
           description: The room ID to get state for.
           required: true
-          x-example: "!abc123:matrix.org"
+          example: "!abc123:matrix.org"
+          schema:
+            type: string
         - in: query
           name: event_id
-          type: string
           description: An event ID in the room to retrieve the state at.
           required: true
-          x-example: "$helloworld:matrix.org"
+          example: $helloworld:matrix.org
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: |-
             The fully resolved state for the room, prior to considering any state
             changes induced by the requested event. Includes the authorization
             chain for the events.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -71,7 +65,7 @@ paths:
                         for precise event formats.
                       properties: {}
                       example:
-                    $ref: "examples/minimal_pdu.json"
+                        $ref: examples/minimal_pdu.json
                   pdus:
                     type: array
                     description: |-
@@ -87,8 +81,10 @@ paths:
                         for precise event formats.
                       properties: {}
                       example:
-                    $ref: "examples/minimal_pdu.json"
+                        $ref: examples/minimal_pdu.json
-            required: ['auth_chain', 'pdus']
+                required:
+                  - auth_chain
+                  - pdus
   "/state_ids/{roomId}":
     get:
       summary: Get all the state event IDs of a given room
@@ -102,22 +98,26 @@ paths:
       parameters:
         - in: path
           name: roomId
-          type: string
           description: The room ID to get state for.
           required: true
-          x-example: "!abc123:matrix.org"
+          example: "!abc123:matrix.org"
+          schema:
+            type: string
         - in: query
           name: event_id
-          type: string
           description: An event ID in the room to retrieve the state at.
           required: true
-          x-example: "$helloworld:matrix.org"
+          example: $helloworld:matrix.org
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: |-
             The fully resolved state for the room, prior to considering any state
             changes induced by the requested event. Includes the authorization
             chain for the events.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -128,46 +128,54 @@ paths:
                       of the room, and their authorization events, recursively.
                     items:
                       type: string
-                example: ["$an_event:example.org"]
+                    example:
+                      - $an_event:example.org
                   pdu_ids:
                     type: array
-                description: |-
+                    description: The fully resolved state of the room at the given event.
-                  The fully resolved state of the room at the given event.
                     items:
                       type: string
-                example: ["$an_event:example.org"]
+                    example:
-            required: ['auth_chain_ids', 'pdu_ids']
+                      - $an_event:example.org
-        404:
+                required:
+                  - auth_chain_ids
+                  - pdu_ids
+        "404":
           description: |-
             The given `event_id` was not found or the server doesn't know about the state at
             that event to return anything useful.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Could not find event $Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg"
                   }
-          schema:
-            "$ref": "../client-server/definitions/errors/error.yaml"
   "/event/{eventId}":
     get:
       summary: Get a single event
-      description: |-
+      description: Retrieves a single event.
-        Retrieves a single event.
       operationId: getEvent
       security:
         - signedRequest: []
       parameters:
         - in: path
           name: eventId
-          type: string
           description: The event ID to get.
           required: true
-          x-example: "$abc123:matrix.org"
+          example: $abc123:matrix.org
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: A transaction containing a single PDU which is the event requested.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/single_pdu_transaction.yaml"
+                $ref: definitions/single_pdu_transaction.yaml
   "/timestamp_to_event/{roomId}":
     get:
       summary: Get the closest event ID to the given timestamp
@@ -202,55 +210,79 @@ paths:
         - accessToken: []
       parameters:
         - in: path
-          type: string
           name: roomId
           description: The ID of the room to search
           required: true
-          x-example: "!636q39766251:matrix.org"
+          example: "!636q39766251:matrix.org"
+          schema:
+            type: string
         - in: query
-          type: integer
           name: ts
           description: |-
             The timestamp to search from, as given in milliseconds
             since the Unix epoch.
           required: true
-          x-example: 1432684800000
+          example: 1432684800000
+          schema:
+            type: integer
         - in: query
-          type: string
-          enum: [f, b]
           name: dir
-          description: |-
+          description: The direction in which to search.  `f` for forwards, `b` for
-            The direction in which to search.  `f` for forwards, `b` for backwards.
+            backwards.
           required: true
-          x-example: f
+          example: f
+          schema:
+            type: string
+            enum:
+              - f
+              - b
       responses:
-        200:
+        "200":
-          description: |-
+          description: An event was found matching the search parameters.
-            An event was found matching the search parameters.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
                   event_id:
                     type: string
-                description: |-
+                    description: The ID of the event found
-                  The ID of the event found
                   origin_server_ts:
                     type: integer
-                description: |-
+                    description: The event's timestamp, in milliseconds since the Unix epoch.
-                  The event's timestamp, in milliseconds since the Unix epoch.
+                required:
-            required: ['event_id', 'origin_server_ts']
+                  - event_id
+                  - origin_server_ts
               examples:
-            application/json: {
+                response:
+                  value: {
                     "event_id": "$143273582443PhrSn:example.org",
                     "origin_server_ts": 1432735824653
                   }
-        404:
+        "404":
-          description: |-
+          description: No event was found.
-            No event was found.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Unable to find event from 1432684800000 in forward direction"
                   }
-          schema:
+servers:
-            "$ref": "../client-server/definitions/errors/error.yaml"
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/federation/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/server-server/invites-v1.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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation Invite User To Room API"
+  title: Matrix Federation Invite User To Room API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/invite/{roomId}/{eventId}":
     put:
@@ -49,23 +38,24 @@ paths:
       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"
+          example: "!abc123:matrix.org"
+          schema:
+            type: string
         - in: path
           name: eventId
-          type: string
           description: The event ID for the invite event, generated by the inviting server.
           required: true
-          x-example: "$abc123:example.org"
+          example: $abc123:example.org
-        - in: body
+          schema:
-          name: body
+            type: string
-          type: object
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               allOf:
-              - $ref: "definitions/invite_event.yaml"
+                - $ref: definitions/invite_event.yaml
                 - type: object
                   properties:
                     unsigned:
@@ -81,9 +71,10 @@ paths:
                             An optional list of [stripped state events](/client-server-api/#stripped-state)
                             to help the receiver of the invite identify the room.
                           items:
-                          $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
+                            $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
                           example:
-                          $ref: "../../event-schemas/examples/invite_room_state.json"
+                            $ref: ../../event-schemas/examples/invite_room_state.json
+              type: object
             example: {
               "room_id": "!somewhere:example.org",
               "type": "m.room.member",
@@ -100,17 +91,21 @@ paths:
                 },
               }
             }
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             The event with the invited server's signature added. All other fields of the events
             should remain untouched. Note that events have a different format depending on the
             room version - check the [room version specification](/rooms) for precise event formats.
+          content:
+            application/json:
               schema:
                 type: array
                 minItems: 2
                 maxItems: 2
                 items:
+                  anyOf:
                     - type: integer
                       description: The value `200`.
                       example: 200
@@ -119,10 +114,12 @@ paths:
                       title: Event Container
                       properties:
                         event:
-                    $ref: "definitions/invite_event.yaml"
+                          $ref: definitions/invite_event.yaml
-                required: ['event']
+                      required:
+                        - event
               examples:
-            application/json: [
+                response:
+                  value: [
                     200,
                     {
                       "event": {
@@ -166,17 +163,35 @@ paths:
                       }
                     }
                   ]
-        403:
+        "403":
           description: |-
             The invite is not allowed. This could be for a number of reasons, including:
 
             * The sender is not allowed to send invites to the target user/homeserver.
             * The homeserver does not permit anyone to invite its users.
             * The homeserver refuses to participate in the room.
+          content:
+            application/json:
               schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "User cannot invite the target user."
                   }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/federation/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/server-server/invites-v2.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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation Invite User To Room API"
+  title: Matrix Federation Invite User To Room API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v2
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/invite/{roomId}/{eventId}":
     put:
@@ -53,20 +42,21 @@ paths:
       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"
+          example: "!abc123:matrix.org"
+          schema:
+            type: string
         - in: path
           name: eventId
-          type: string
           description: The event ID for the invite event, generated by the inviting server.
           required: true
-          x-example: "$abc123:example.org"
+          example: $abc123:example.org
-        - in: body
+          schema:
-          name: body
+            type: string
-          type: object
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               properties:
@@ -75,17 +65,19 @@ paths:
                   description: The version of the room where the user is being invited to.
                   example: "2"
                 event:
-                $ref: "definitions/invite_event.yaml"
+                  $ref: definitions/invite_event.yaml
                 invite_room_state:
                   type: array
                   description: |-
                     An optional list of [stripped state events](/client-server-api/#stripped-state)
                     to help the receiver of the invite identify the room.
                   items:
-                  $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
+                    $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
                   example:
-                  $ref: "../../event-schemas/examples/invite_room_state.json"
+                    $ref: ../../event-schemas/examples/invite_room_state.json
-            required: ['room_version', 'event']
+              required:
+                - room_version
+                - event
             example: {
               "room_version": "2",
               "event": {
@@ -105,22 +97,27 @@ paths:
                 }
               }
             }
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             The event with the invited server's signature added. All other fields of the events
             should remain untouched. Note that events have a different format depending on the
             room version - check the [room version specification](/rooms) for precise event formats.
+          content:
+            application/json:
               schema:
                 type: object
                 description: An object containing the signed invite event.
                 title: Event Container
                 properties:
                   event:
-                $ref: "definitions/invite_event.yaml"
+                    $ref: definitions/invite_event.yaml
-            required: ['event']
+                required:
+                  - event
               examples:
-            application/json: {
+                response:
+                  value: {
                     "event": {
                       "room_id": "!somewhere:example.org",
                       "type": "m.room.member",
@@ -161,21 +158,7 @@ paths:
                       }
                     }
                   }
-        403:
+        "400":
-          description: |-
-            The invite is not allowed. This could be for a number of reasons, including:
-
-            * The sender is not allowed to send invites to the target user/homeserver.
-            * The homeserver does not permit anyone to invite its users.
-            * The homeserver refuses to participate in the room.
-          schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
-          examples:
-            application/json: {
-              "errcode": "M_FORBIDDEN",
-              "error": "User cannot invite the target user."
-            }
-        400:
           description: |-
             The request is invalid or the room the server is attempting
             to join has a version that is not listed in the `ver`
@@ -183,9 +166,11 @@ paths:
 
             The error should be passed through to clients so that they
             may give better feedback to users.
+          content:
+            application/json:
               schema:
                 allOf:
-              - $ref: "../client-server/definitions/errors/error.yaml"
+                  - $ref: ../client-server/definitions/errors/error.yaml
                   - type: object
                     properties:
                       room_version:
@@ -194,8 +179,41 @@ paths:
                           The version of the room. Required if the `errcode`
                           is `M_INCOMPATIBLE_ROOM_VERSION`.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_INCOMPATIBLE_ROOM_VERSION",
                     "error": "Your homeserver does not support the features required to join this room",
                     "room_version": "3"
                   }
+        "403":
+          description: |-
+            The invite is not allowed. This could be for a number of reasons, including:
+
+            * The sender is not allowed to send invites to the target user/homeserver.
+            * The homeserver does not permit anyone to invite its users.
+            * The homeserver refuses to participate in the room.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "User cannot invite the target user."
+                  }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/federation/v2
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/server-server/joins-v1.yaml

@@ -12,21 +12,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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation Join Room API"
+  title: Matrix Federation Join Room API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/make_join/{roomId}/{userId}":
     get:
@@ -40,33 +29,40 @@ paths:
       parameters:
         - in: path
           name: roomId
-          type: string
           description: The room ID that is about to be joined.
           required: true
-          x-example: "!abc123:matrix.org"
+          example: "!abc123:matrix.org"
+          schema:
+            type: string
         - in: path
           name: userId
-          type: string
           description: The user ID the join event will be for.
           required: true
-          x-example: "@someone:example.org"
+          example: "@someone:example.org"
-        - in: query
+          schema:
-          type: array
-          items:
             type: string
+        - in: query
           name: ver
           description: |-
             The room versions the sending server has support for. Defaults
             to `[1]`.
-          x-example: ["1", "2"]
+          example:
+            - "1"
+            - "2"
+          schema:
+            type: array
+            items:
+              type: string
       responses:
-        200:
+        "200":
           description: |-
             A template to be used for the rest of the [Joining Rooms](/server-server-api/#joining-rooms) handshake. Note that
             events have a different format depending on the room version - check the
             [room version specification](/rooms) for precise event formats. **The response body
             here describes the common event fields in more detail and may be missing other
             required fields for a PDU.**
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -91,7 +87,7 @@ paths:
                       origin:
                         type: string
                         description: The name of the resident homeserver.
-                    example: "matrix.org"
+                        example: matrix.org
                       origin_server_ts:
                         type: integer
                         format: int64
@@ -100,7 +96,7 @@ paths:
                       type:
                         type: string
                         description: The value `m.room.member`.
-                    example: "m.room.member"
+                        example: m.room.member
                       state_key:
                         type: string
                         description: The user ID of the joining member.
@@ -109,12 +105,13 @@ paths:
                         type: object
                         title: Membership Event Content
                         description: The content of the event.
-                    example: {"membership": "join"}
+                        example:
+                          membership: join
                         properties:
                           membership:
                             type: string
                             description: The value `join`.
-                        example: "join"
+                            example: join
                           join_authorised_via_users_server:
                             type: string
                             x-addedInMatrixVersion: "1.2"
@@ -127,7 +124,8 @@ paths:
                               the room being joined that is able to issue invites to other
                               users. This is used in later validation of the auth rules for
                               the `m.room.member` event.
-                    required: ['membership']
+                        required:
+                          - membership
                     required:
                       - state_key
                       - origin
@@ -136,7 +134,8 @@ paths:
                       - content
                       - sender
               examples:
-            application/json: {
+                response:
+                  value: {
                     "room_version": "2",
                     "event": {
                       "room_id": "!somewhere:example.org",
@@ -151,7 +150,7 @@ paths:
                       }
                     }
                   }
-        400:
+        "400":
           description: |-
             The request is invalid, the room the server is attempting
             to join has a version that is not listed in the `ver`
@@ -177,9 +176,11 @@ paths:
             resident server would be unable to meet the auth rules governing
             `join_authorised_via_users_server` on the resulting `m.room.member`
             event.
+          content:
+            application/json:
               schema:
                 allOf:
-              - $ref: "../client-server/definitions/errors/error.yaml"
+                  - $ref: ../client-server/definitions/errors/error.yaml
                   - type: object
                     properties:
                       room_version:
@@ -188,34 +189,40 @@ paths:
                           The version of the room. Required if the `errcode`
                           is `M_INCOMPATIBLE_ROOM_VERSION`.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_INCOMPATIBLE_ROOM_VERSION",
                     "error": "Your homeserver does not support the features required to join this room",
                     "room_version": "3"
                   }
-        403:
+        "403":
-          schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
           description: |-
             The room that the joining server is attempting to join does not permit the user
             to join.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
-              "error": "You are not invited to this room",
+                    "error": "You are not invited to this room"
                   }
-        404:
+        "404":
-          schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
           description: |-
             The room that the joining server is attempting to join is unknown
             to the receiving server.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
-              "error": "Unknown room",
+                    "error": "Unknown room"
                   }
-
   "/send_join/{roomId}/{eventId}":
     put:
       deprecated: true
@@ -237,20 +244,21 @@ paths:
       parameters:
         - in: path
           name: roomId
-          type: string
           description: The room ID that is about to be joined.
           required: true
-          x-example: "!abc123:matrix.org"
+          example: "!abc123:matrix.org"
+          schema:
+            type: string
         - in: path
           name: eventId
-          type: string
           description: The event ID for the join event.
           required: true
-          x-example: "$abc123:example.org"
+          example: $abc123:example.org
-        - in: body
+          schema:
-          name: body
+            type: string
-          type: object
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               properties:
@@ -261,7 +269,7 @@ paths:
                 origin:
                   type: string
                   description: The name of the joining homeserver.
-                example: "matrix.org"
+                  example: matrix.org
                 origin_server_ts:
                   type: integer
                   format: int64
@@ -270,7 +278,7 @@ paths:
                 type:
                   type: string
                   description: The value `m.room.member`.
-                example: "m.room.member"
+                  example: m.room.member
                 state_key:
                   type: string
                   description: The user ID of the joining member.
@@ -279,12 +287,13 @@ paths:
                   type: object
                   title: Membership Event Content
                   description: The content of the event.
-                example: {"membership": "join"}
+                  example:
+                    membership: join
                   properties:
                     membership:
                       type: string
                       description: The value `join`.
-                    example: "join"
+                      example: join
                     join_authorised_via_users_server:
                       type: string
                       x-addedInMatrixVersion: "1.2"
@@ -302,7 +311,8 @@ paths:
                         valid signature on the event. If the resident server is receiving
                         the `/send_join` request, the signature must be added before sending
                         or persisting the event to other servers.
-                required: ['membership']
+                  required:
+                    - membership
               required:
                 - state_key
                 - sender
@@ -310,27 +320,18 @@ paths:
                 - origin_server_ts
                 - type
                 - content
-          example: {
+        required: true
-            "room_id": "!somewhere:example.org",
-            "type": "m.room.member",
-            "state_key": "@someone:example.org",
-            "origin": "example.org",
-            "origin_server_ts": 1549041175876,
-            "sender": "@someone:example.org",
-            "content": {
-                "membership": "join",
-                "join_authorised_via_users_server": "@anyone:resident.example.org"
-            }
-          }
       responses:
-        200:
+        "200":
-          description: |-
+          description: The join event has been accepted into the room.
-            The join event has been accepted into the room.
+          content:
+            application/json:
               schema:
                 type: array
                 minItems: 2
                 maxItems: 2
                 items:
+                  anyOf:
                     - type: integer
                       description: The value `200`.
                       example: 200
@@ -354,9 +355,6 @@ paths:
                             description: |-
                               The [PDUs](/server-server-api/#pdus) that make up the auth chain. The event format varies depending
                               on the room version - check the [room version specification](/rooms) for precise event formats.
-                      schema:
-                        type: object
-                        properties: {}
                         state:
                           type: array
                           description: |-
@@ -370,17 +368,43 @@ paths:
                             description: |-
                               The [PDUs](/server-server-api/#pdus) for the fully resolved state of the room. The event format varies depending
                               on the room version - check the [room version specification](/rooms) for precise event formats.
-                      schema:
+                      required:
-                        type: object
+                        - auth_chain
-                        properties: {}
+                        - state
-                required: ["auth_chain", "state", "origin"]
+                        - origin
               examples:
-            application/json: [
+                response:
+                  value: [
                     200,
                     {
                       "origin": "matrix.org",
-                "auth_chain": [{"$ref": "examples/minimal_pdu.json"}],
+                      "auth_chain": [
-                "state": [{"$ref": "examples/minimal_pdu.json"}],
+                        {
-                "event": {"$ref": "examples/pdu_v4_join_membership.json"}
+                          "$ref": "examples/minimal_pdu.json"
+                        }
+                      ],
+                      "state": [
+                        {
+                          "$ref": "examples/minimal_pdu.json"
+                        }
+                      ],
+                      "event": {
+                        "$ref": "examples/pdu_v4_join_membership.json"
+                      }
                     }
                   ]
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/federation/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/server-server/joins-v2.yaml

@@ -12,21 +12,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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation Join Room API"
+  title: Matrix Federation Join Room API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v2
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   # Note: there is no v2 of make_join (yet)
   "/send_join/{roomId}/{eventId}":
@@ -55,19 +44,20 @@ paths:
       parameters:
         - in: path
           name: roomId
-          type: string
           description: The room ID that is about to be joined.
           required: true
-          x-example: "!abc123:matrix.org"
+          example: "!abc123:matrix.org"
+          schema:
+            type: string
         - in: path
           name: eventId
-          type: string
           description: The event ID for the join event.
           required: true
-          x-example: "$abc123:example.org"
+          example: $abc123:example.org
+          schema:
+            type: string
         - in: query
           name: omit_members
-          type: boolean
           description: |-
             If `true`, indicates that that calling server can accept a reduced
             response, in which membership events are omitted from `state` and
@@ -83,10 +73,11 @@ paths:
             response `state` field, and include the auth chains for these
             membership events in the response `auth_chain` field.
           x-addedInMatrixVersion: "1.6"
-        - in: body
+          schema:
-          name: body
+            type: boolean
-          type: object
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               properties:
@@ -97,7 +88,7 @@ paths:
                 origin:
                   type: string
                   description: The name of the joining homeserver.
-                example: "matrix.org"
+                  example: matrix.org
                 origin_server_ts:
                   type: integer
                   format: int64
@@ -106,7 +97,7 @@ paths:
                 type:
                   type: string
                   description: The value `m.room.member`.
-                example: "m.room.member"
+                  example: m.room.member
                 state_key:
                   type: string
                   description: The user ID of the joining member.
@@ -115,12 +106,13 @@ paths:
                   type: object
                   title: Membership Event Content
                   description: The content of the event.
-                example: {"membership": "join"}
+                  example:
+                    membership: join
                   properties:
                     membership:
                       type: string
                       description: The value `join`.
-                    example: "join"
+                      example: join
                     join_authorised_via_users_server:
                       type: string
                       x-addedInMatrixVersion: "1.2"
@@ -138,7 +130,8 @@ paths:
                         valid signature on the event. If the resident server is receiving
                         the `/send_join` request, the signature must be added before sending
                         or persisting the event to other servers.
-                required: ['membership']
+                  required:
+                    - membership
               required:
                 - state_key
                 - sender
@@ -158,51 +151,12 @@ paths:
                   "join_authorised_via_users_server": "@anyone:resident.example.org"
               }
             }
+        required: true
       responses:
-        400:
+        "200":
-          description: |-
+          description: The join event has been accepted into the room.
-            The request is invalid in some way.
+          content:
-
+            application/json:
-            The error should be passed through to clients so that they
-            may give better feedback to users.
-
-            New in `v1.2`, the following error conditions might happen:
-
-            If the room is [restricted](/client-server-api/#restricted-rooms)
-            and none of the conditions can be validated by the server then
-            the `errcode` `M_UNABLE_TO_AUTHORISE_JOIN` must be used. This can
-            happen if the server does not know about any of the rooms listed
-            as conditions, for example.
-
-            `M_UNABLE_TO_GRANT_JOIN` is returned to denote that a different
-            server should be attempted for the join. This is typically because
-            the resident server can see that the joining user satisfies one or
-            more conditions, such as in the case of
-            [restricted rooms](/client-server-api/#restricted-rooms), but the
-            resident server would be unable to meet the auth rules governing
-            `join_authorised_via_users_server` on the resulting `m.room.member`
-            event.
-          schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
-          examples:
-            application/json: {
-              "errcode": "M_UNABLE_TO_GRANT_JOIN",
-              "error": "This server cannot send invites to you."
-            }
-        403:
-          schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
-          description: |-
-            The room that the joining server is attempting to join does not permit the user
-            to join.
-          examples:
-            application/json: {
-              "errcode": "M_FORBIDDEN",
-              "error": "You are not invited to this room",
-            }
-        200:
-          description: |-
-            The join event has been accepted into the room.
               schema:
                 type: object
                 properties:
@@ -230,9 +184,6 @@ paths:
                     items:
                       type: object
                       title: PDU
-                  schema:
-                    type: object
-                    properties: {}
                     x-changedInMatrixVersion:
                       "1.6": |-
                         reworded to include only consider state events returned in
@@ -249,12 +200,8 @@ paths:
                     items:
                       type: object
                       title: PDU
-                  schema:
-                    type: object
-                    properties: {}
                     x-changedInMatrixVersion:
-                  "1.6": |-
+                      "1.6": permit omission of membership events.
-                    permit omission of membership events.
                   event:
                     type: object
                     title: SignedMembershipEvent
@@ -272,13 +219,92 @@ paths:
                       A list of the servers active in the room (ie, those with joined members) before the join.
                     items:
                       type: string
-            required: ["auth_chain", "state", "origin"]
+                required:
+                  - auth_chain
+                  - state
+                  - origin
               examples:
-            application/json: {
+                response:
+                  value: {
                     "origin": "matrix.org",
-              "auth_chain": [{"$ref": "examples/minimal_pdu.json"}],
+                    "auth_chain": [
-              "state": [{"$ref": "examples/minimal_pdu.json"}],
+                      {
-              "event": {"$ref": "examples/pdu_v4_join_membership.json"},
+                        "$ref": "examples/minimal_pdu.json"
+                      }
+                    ],
+                    "state": [
+                      {
+                        "$ref": "examples/minimal_pdu.json"
+                      }
+                    ],
+                    "event": {
+                      "$ref": "examples/pdu_v4_join_membership.json"
+                    },
                     "members_omitted": true,
-              "servers_in_room": ["matrix.org", "example.com"]
+                    "servers_in_room": [
+                      "matrix.org",
+                      "example.com"
+                    ]
+                  }
+        "400":
+          description: |-
+            The request is invalid in some way.
+
+            The error should be passed through to clients so that they
+            may give better feedback to users.
+
+            New in `v1.2`, the following error conditions might happen:
+
+            If the room is [restricted](/client-server-api/#restricted-rooms)
+            and none of the conditions can be validated by the server then
+            the `errcode` `M_UNABLE_TO_AUTHORISE_JOIN` must be used. This can
+            happen if the server does not know about any of the rooms listed
+            as conditions, for example.
+
+            `M_UNABLE_TO_GRANT_JOIN` is returned to denote that a different
+            server should be attempted for the join. This is typically because
+            the resident server can see that the joining user satisfies one or
+            more conditions, such as in the case of
+            [restricted rooms](/client-server-api/#restricted-rooms), but the
+            resident server would be unable to meet the auth rules governing
+            `join_authorised_via_users_server` on the resulting `m.room.member`
+            event.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_UNABLE_TO_GRANT_JOIN",
+                    "error": "This server cannot send invites to you."
+                  }
+        "403":
+          description: |-
+            The room that the joining server is attempting to join does not permit the user
+            to join.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not invited to this room"
                   }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/federation/v2
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/server-server/keys_query.yaml

@@ -11,19 +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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation Key Exchange API"
+  title: Matrix Federation Key Exchange API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/key/v2
-consumes:
-  - application/json
-produces:
-  - application/json
 paths:
   "/query/{serverName}":
     get:
@@ -35,38 +26,42 @@ paths:
       parameters:
         - in: path
           name: serverName
-          type: string
           description: The server's DNS name to query
           required: true
-          x-example: matrix.org
+          example: matrix.org
+          schema:
+            type: string
         - in: query
           name: minimum_valid_until_ts
-          type: integer
-          format: int64
           description: |-
             A millisecond POSIX timestamp in milliseconds indicating when the returned
             certificates will need to be valid until to be useful to the requesting server.
 
             If not supplied, the current time as determined by the notary server is used.
           required: false
-          x-example: 1234567890
+          example: 1234567890
+          schema:
+            type: integer
+            format: int64
       responses:
-        200:
+        "200":
           description: |-
             The keys for the server, or an empty array if the server could not be reached
             and no cached keys were available.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/keys_query_response.yaml"
+                $ref: definitions/keys_query_response.yaml
-  "/query":
+  /query:
     post:
       summary: Query for several server's keys
       description: |-
         Query for keys from multiple servers in a batch format. The receiving (notary)
         server must sign the keys returned by the queried servers.
       operationId: bulkPerspectivesKeyQuery
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
             schema:
               type: object
               example: {
@@ -93,7 +88,6 @@ paths:
                     given.
                   additionalProperties:
                     type: object
-                  name: ServerName
                     description: The server names to query.
                     additionalProperties:
                       type: object
@@ -111,12 +105,27 @@ paths:
                             If not supplied, the current time as determined by the notary
                             server is used.
                           example: 1234567890
-            required: ['server_keys']
+              required:
+                - server_keys
       responses:
-        200:
+        "200":
           description: |-
             The keys for the queried servers, signed by the notary server. Servers which
             are offline and have no cached keys will not be included in the result. This
             may result in an empty array.
+          content:
+            application/json:
               schema:
-            $ref: "definitions/keys_query_response.yaml"
+                $ref: definitions/keys_query_response.yaml
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/key/v2

data/api/server-server/keys_server.yaml

@@ -11,19 +11,12 @@
 # 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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation Key Exchange API"
+  title: Matrix Federation Key Exchange API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/key/v2
-produces:
-  - application/json
 paths:
-  "/server":
+  /server:
     get:
       summary: Get the homeserver's public key(s)
       description: |-
@@ -44,7 +37,21 @@ paths:
         checked.
       operationId: getServerKey
       responses:
-        200:
+        "200":
           description: The homeserver's keys
+          content:
+            application/json:
               schema:
-            $ref: "definitions/keys.yaml"
+                $ref: definitions/keys.yaml
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/key/v2

data/api/server-server/knocks.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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation Knock Room API"
+  title: Matrix Federation Knock Room API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/make_knock/{roomId}/{userId}":
     get:
@@ -40,40 +29,45 @@ paths:
       parameters:
         - in: path
           name: roomId
-          type: string
           description: The room ID that is about to be knocked.
           required: true
-          x-example: "!abc123:example.org"
+          example: "!abc123:example.org"
+          schema:
+            type: string
         - in: path
           name: userId
-          type: string
           description: The user ID the knock event will be for.
           required: true
-          x-example: "@someone:example.org"
+          example: "@someone:example.org"
+          schema:
+            type: string
         - in: query
+          name: ver
+          description: The room versions the sending server has support for.
+          required: true  # knocking was supported in v7
+          example:
+            - "1"
+            - "7"
+          schema:
             type: array
             items:
               type: string
-          name: ver
-          description: |-
-            The room versions the sending server has support for.
-          required: true  # knocking was supported in v7
-          x-example: ["1", "7"]
       responses:
-        200:
+        "200":
           description: |-
             A template to be used for the rest of the [Knocking Rooms](/server-server-api/#knocking-rooms)
             handshake. Note that events have a different format depending on room version - check the
             [room version specification](/rooms) for precise event formats. **The response body
             here describes the common event fields in more detail and may be missing other
             required fields for a PDU.**
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
                   room_version:
                     type: string
-                description: |-
+                    description: The version of the room where the server is trying to knock.
-                  The version of the room where the server is trying to knock.
                     example: "7"
                   event:
                     description: |-
@@ -90,7 +84,7 @@ paths:
                       origin:
                         type: string
                         description: The name of the resident homeserver.
-                    example: "matrix.org"
+                        example: matrix.org
                       origin_server_ts:
                         type: integer
                         format: int64
@@ -99,7 +93,7 @@ paths:
                       type:
                         type: string
                         description: The value `m.room.member`.
-                    example: "m.room.member"
+                        example: m.room.member
                       state_key:
                         type: string
                         description: The user ID of the knocking member.
@@ -108,13 +102,15 @@ paths:
                         type: object
                         title: Membership Event Content
                         description: The content of the event.
-                    example: {"membership": "knock"}
+                        example:
+                          membership: knock
                         properties:
                           membership:
                             type: string
                             description: The value `knock`.
-                        example: "knock"
+                            example: knock
-                    required: ['membership']
+                        required:
+                          - membership
                     required:
                       - state_key
                       - origin
@@ -126,7 +122,8 @@ paths:
                   - room_version  # knocking was added in v7
                   - event
               examples:
-            application/json: {
+                response:
+                  value: {
                     "room_version": "7",
                     "event": {
                       "room_id": "!somewhere:example.org",
@@ -140,7 +137,7 @@ paths:
                       }
                     }
                   }
-        400:
+        "400":
           description: |-
             The request is invalid or the room the server is attempting
             to knock upon has a version that is not listed in the `ver`
@@ -148,9 +145,11 @@ paths:
 
             The error should be passed through to clients so that they
             may give better feedback to users.
+          content:
+            application/json:
               schema:
                 allOf:
-              - $ref: "../client-server/definitions/errors/error.yaml"
+                  - $ref: ../client-server/definitions/errors/error.yaml
                   - type: object
                     properties:
                       room_version:
@@ -159,36 +158,42 @@ paths:
                           The version of the room. Required if the `errcode`
                           is `M_INCOMPATIBLE_ROOM_VERSION`.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_INCOMPATIBLE_ROOM_VERSION",
                     "error": "Your homeserver does not support the features required to knock on this room",
                     "room_version": "7"
                   }
-        404:
+        "403":
           description: |-
-            The room that the knocking server is attempting to knock upon is unknown
+            The knocking server or user is not permitted to knock on the room, such as when the
-            to the receiving server.
+            server/user is banned or the room is not set up for receiving knocks.
+          content:
+            application/json:
               schema:
                 allOf:
-              - $ref: "../client-server/definitions/errors/error.yaml"
+                  - $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
-              "errcode": "M_NOT_FOUND",
+                  value: {
-              "error": "Unknown room",
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not permitted to knock on this room"
                   }
-        403:
+        "404":
           description: |-
-            The knocking server or user is not permitted to knock on the room, such as when the
+            The room that the knocking server is attempting to knock upon is unknown
-            server/user is banned or the room is not set up for receiving knocks.
+            to the receiving server.
+          content:
+            application/json:
               schema:
                 allOf:
-              - $ref: "../client-server/definitions/errors/error.yaml"
+                  - $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
-              "errcode": "M_FORBIDDEN",
+                  value: {
-              "error": "You are not permitted to knock on this room",
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Unknown room"
                   }
-
   "/send_knock/{roomId}/{eventId}":
     put:
       x-addedInMatrixVersion: "1.1"
@@ -207,20 +212,21 @@ paths:
       parameters:
         - in: path
           name: roomId
-          type: string
           description: The room ID that is about to be knocked upon.
           required: true
-          x-example: "!abc123:example.org"
+          example: "!abc123:example.org"
+          schema:
+            type: string
         - in: path
           name: eventId
-          type: string
           description: The event ID for the knock event.
           required: true
-          x-example: "$abc123:example.org"
+          example: $abc123:example.org
-        - in: body
+          schema:
-          name: body
+            type: string
-          type: object
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               properties:
@@ -231,7 +237,7 @@ paths:
                 origin:
                   type: string
                   description: The name of the knocking homeserver.
-                example: "matrix.org"
+                  example: matrix.org
                 origin_server_ts:
                   type: integer
                   format: int64
@@ -240,7 +246,7 @@ paths:
                 type:
                   type: string
                   description: The value `m.room.member`.
-                example: "m.room.member"
+                  example: m.room.member
                 state_key:
                   type: string
                   description: The user ID of the knocking member.
@@ -249,13 +255,15 @@ paths:
                   type: object
                   title: Membership Event Content
                   description: The content of the event.
-                example: {"membership": "knock"}
+                  example:
+                    membership: knock
                   properties:
                     membership:
                       type: string
                       description: The value `knock`.
-                    example: "knock"
+                      example: knock
-                required: ['membership']
+                  required:
+                    - membership
               required:
                 - state_key
                 - sender
@@ -274,50 +282,77 @@ paths:
                   "membership": "knock"
               }
             }
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             Information about the room to pass along to clients regarding the
             knock.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
                   knock_room_state:
                     type: array
                     items:
-                  $ref: "../../event-schemas/schema/core-event-schema/stripped_state.yaml"
+                      $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
                     description: |-
                       A list of [stripped state events](/client-server-api/#stripped-state)
                       to help the initiator of the knock identify the room.
                     example:
-                  $ref: "../../event-schemas/examples/knock_room_state.json"
+                      $ref: ../../event-schemas/examples/knock_room_state.json
-            required: ['knock_room_state']
+                required:
+                  - knock_room_state
               examples:
-            application/json: {
+                response:
-              "knock_room_state": {"$ref": "../../event-schemas/examples/knock_room_state.json"}
+                  value: {
+                    "knock_room_state": {
+                      "$ref": "../../event-schemas/examples/knock_room_state.json"
+                    }
                   }
-        404:
+        "403":
           description: |-
-            The room that the knocking server is attempting to knock upon is unknown
+            The knocking server or user is not permitted to knock on the room, such as when the
-            to the receiving server.
+            server/user is banned or the room is not set up for receiving knocks.
+          content:
+            application/json:
               schema:
                 allOf:
-              - $ref: "../client-server/definitions/errors/error.yaml"
+                  - $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
-              "errcode": "M_NOT_FOUND",
+                  value: {
-              "error": "Unknown room",
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not permitted to knock on this room"
                   }
-        403:
+        "404":
           description: |-
-            The knocking server or user is not permitted to knock on the room, such as when the
+            The room that the knocking server is attempting to knock upon is unknown
-            server/user is banned or the room is not set up for receiving knocks.
+            to the receiving server.
+          content:
+            application/json:
               schema:
                 allOf:
-              - $ref: "../client-server/definitions/errors/error.yaml"
+                  - $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
-              "errcode": "M_FORBIDDEN",
+                  value: {
-              "error": "You are not permitted to knock on this room",
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Unknown room"
                   }
-
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/federation/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/server-server/leaving-v1.yaml

@@ -12,21 +12,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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation Leave Room API"
+  title: Matrix Federation Leave Room API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/make_leave/{roomId}/{userId}":
     get:
@@ -40,24 +29,28 @@ paths:
       parameters:
         - in: path
           name: roomId
-          type: string
           description: The room ID that is about to be left.
           required: true
-          x-example: "!abc123:matrix.org"
+          example: "!abc123:matrix.org"
+          schema:
+            type: string
         - in: path
           name: userId
-          type: string
           description: The user ID the leave event will be for.
           required: true
-          x-example: "@someone:example.org"
+          example: "@someone:example.org"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: |-
             A template to be used to call `/send_leave`. Note that
             events have a different format depending on the room version - check the
             [room version specification](/rooms) for precise event formats. **The response body
             here describes the common event fields in more detail and may be missing other
             required fields for a PDU.**
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -82,7 +75,7 @@ paths:
                       origin:
                         type: string
                         description: The name of the resident homeserver.
-                    example: "matrix.org"
+                        example: matrix.org
                       origin_server_ts:
                         type: integer
                         format: int64
@@ -91,7 +84,7 @@ paths:
                       type:
                         type: string
                         description: The value `m.room.member`.
-                    example: "m.room.member"
+                        example: m.room.member
                       state_key:
                         type: string
                         description: The user ID of the leaving member.
@@ -100,13 +93,15 @@ paths:
                         type: object
                         title: Membership Event Content
                         description: The content of the event.
-                    example: {"membership": "leave"}
+                        example:
+                          membership: leave
                         properties:
                           membership:
                             type: string
                             description: The value `leave`.
-                        example: "leave"
+                            example: leave
-                    required: ['membership']
+                        required:
+                          - membership
                     required:
                       - state_key
                       - sender
@@ -115,7 +110,8 @@ paths:
                       - type
                       - content
               examples:
-            application/json: {
+                response:
+                  value: {
                     "room_version": "2",
                     "event": {
                       "room_id": "!somewhere:example.org",
@@ -129,13 +125,16 @@ paths:
                       }
                     }
                   }
-        403:
+        "403":
-          description: |-
+          description: The request is not authorized. This could mean that the user is not
-            The request is not authorized. This could mean that the user is not in the room.
+            in the room.
+          content:
+            application/json:
               schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_FORBIDDEN",
                     "error": "User is not in the room."
                   }
@@ -160,20 +159,21 @@ paths:
       parameters:
         - in: path
           name: roomId
-          type: string
           description: The room ID that is about to be left.
           required: true
-          x-example: "!abc123:matrix.org"
+          example: "!abc123:matrix.org"
+          schema:
+            type: string
         - in: path
           name: eventId
-          type: string
           description: The event ID for the leave event.
           required: true
-          x-example: "$abc123:example.org"
+          example: $abc123:example.org
-        - in: body
+          schema:
-          name: body
+            type: string
-          type: object
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               properties:
@@ -184,7 +184,7 @@ paths:
                 origin:
                   type: string
                   description: The name of the leaving homeserver.
-                example: "matrix.org"
+                  example: matrix.org
                 origin_server_ts:
                   type: integer
                   format: int64
@@ -193,7 +193,7 @@ paths:
                 type:
                   type: string
                   description: The value `m.room.member`.
-                example: "m.room.member"
+                  example: m.room.member
                 state_key:
                   type: string
                   description: The user ID of the leaving member.
@@ -202,13 +202,15 @@ paths:
                   type: object
                   title: Membership Event Content
                   description: The content of the event.
-                example: {"membership": "leave"}
+                  example:
+                    membership: leave
                   properties:
                     membership:
                       type: string
                       description: The value `leave`.
-                    example: "leave"
+                      example: leave
-                required: ['membership']
+                  required:
+                    - membership
                 depth:
                   type: integer
                   description: This field must be present but is ignored; it may be 0.
@@ -221,27 +223,20 @@ paths:
                 - type
                 - depth
                 - content
-          example: {
+        required: true
-            "room_id": "!somewhere:example.org",
-            "type": "m.room.member",
-            "state_key": "@someone:example.org",
-            "origin": "example.org",
-            "origin_server_ts": 1549041175876,
-            "sender": "@someone:example.org",
-            "content": {
-                "membership": "leave"
-            }
-          }
       responses:
-        200:
+        "200":
           description: |-
             An empty response to indicate the event was accepted into the graph by
             the receiving homeserver.
+          content:
+            application/json:
               schema:
                 type: array
                 minItems: 2
                 maxItems: 2
                 items:
+                  anyOf:
                     - type: integer
                       description: The value `200`.
                       example: 200
@@ -249,4 +244,23 @@ paths:
                       title: Empty Object
                       description: An empty object.
               examples:
-            application/json: [200, {}]
+                response:
+                  value: [
+                    200,
+                    {}
+                  ]
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/federation/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/server-server/leaving-v2.yaml

@@ -12,21 +12,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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation Leave Room API"
+  title: Matrix Federation Leave Room API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v2
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   # Note: there is no v2 of make_leave (yet)
   "/send_leave/{roomId}/{eventId}":
@@ -55,20 +44,21 @@ paths:
       parameters:
         - in: path
           name: roomId
-          type: string
           description: The room ID that is about to be left.
           required: true
-          x-example: "!abc123:matrix.org"
+          example: "!abc123:matrix.org"
+          schema:
+            type: string
         - in: path
           name: eventId
-          type: string
           description: The event ID for the leave event.
           required: true
-          x-example: "$abc123:example.org"
+          example: $abc123:example.org
-        - in: body
+          schema:
-          name: body
+            type: string
-          type: object
+      requestBody:
-          required: true
+        content:
+          application/json:
             schema:
               type: object
               properties:
@@ -79,7 +69,7 @@ paths:
                 origin:
                   type: string
                   description: The name of the leaving homeserver.
-                example: "matrix.org"
+                  example: matrix.org
                 origin_server_ts:
                   type: integer
                   format: int64
@@ -88,7 +78,7 @@ paths:
                 type:
                   type: string
                   description: The value `m.room.member`.
-                example: "m.room.member"
+                  example: m.room.member
                 state_key:
                   type: string
                   description: The user ID of the leaving member.
@@ -97,13 +87,15 @@ paths:
                   type: object
                   title: Membership Event Content
                   description: The content of the event.
-                example: {"membership": "leave"}
+                  example:
+                    membership: leave
                   properties:
                     membership:
                       type: string
                       description: The value `leave`.
-                    example: "leave"
+                      example: leave
-                required: ['membership']
+                  required:
+                    - membership
                 depth:
                   type: integer
                   description: This field must be present but is ignored; it may be 0.
@@ -127,14 +119,33 @@ paths:
                   "membership": "leave"
               }
             }
+        required: true
       responses:
-        200:
+        "200":
           description: |-
             An empty response to indicate the event was accepted into the graph by
             the receiving homeserver.
+          content:
+            application/json:
               schema:
                 type: object
                 title: Empty Object
                 description: An empty object.
               examples:
-            application/json: {}
+                response:
+                  value: {}
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/federation/v2
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/server-server/openid.yaml

@@ -12,19 +12,12 @@
 # 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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation OpenID API"
+  title: Matrix Federation OpenID API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v1
-produces:
-  - application/json
 paths:
-  "/openid/userinfo":
+  /openid/userinfo:
     get:
       summary: Exchange an OpenID token for user information
       description: |-
@@ -35,15 +28,16 @@ paths:
       parameters:
         - in: query
           name: access_token
-          type: string
+          description: The OpenID access token to get information about the owner for.
-          description: |-
-            The OpenID access token to get information about the owner for.
           required: true
-          x-example: SomeT0kenHere
+          example: SomeT0kenHere
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description: |-
+          description: Information about the user who generated the OpenID access token.
-            Information about the user who generated the OpenID access token.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -51,13 +45,29 @@ paths:
                     type: string
                     description: The Matrix User ID who generated the token.
                     example: "@alice:example.com"
-            required: ['sub']
+                required:
-        401:
+                  - sub
+        "401":
           description: The token was not recognized or has expired.
+          content:
+            application/json:
               schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_UNKNOWN_TOKEN",
                     "error": "Access token unknown or expired"
                   }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/federation/v1

data/api/server-server/public_rooms.yaml

@@ -11,21 +11,12 @@
 # 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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation Public Rooms API"
+  title: Matrix Federation Public Rooms API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v1
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
-  "/publicRooms":
+  /publicRooms:
     get:
       summary: Get all the public rooms for a homeserver
       description: |-
@@ -38,36 +29,41 @@ paths:
       parameters:
         - in: query
           name: limit
+          description: The maximum number of rooms to return. Defaults to 0 (no limit).
+          example: 10
+          schema:
             type: integer
-          description: |-
-            The maximum number of rooms to return. Defaults to 0 (no limit).
-          x-example: 10
         - in: query
           name: since
-          type: string
           description: |-
             A pagination token from a previous call to this endpoint to fetch more
             rooms.
-          x-example: "GetMoreRoomsTokenHere"
+          example: GetMoreRoomsTokenHere
+          schema:
+            type: string
         - in: query
           name: include_all_networks
-          type: boolean
           description: |-
             Whether or not to include all networks/protocols defined by application
             services on the homeserver. Defaults to false.
-          x-example: false
+          example: false
+          schema:
+            type: boolean
         - in: query
           name: third_party_instance_id
-          type: string
           description: |-
             The specific third-party network/protocol to request from the homeserver.
             Can only be used if `include_all_networks` is false.
-          x-example: "irc"
+          example: irc
+          schema:
+            type: string
       responses:
-        200:
+        "200":
           description: The public room list for the homeserver.
+          content:
+            application/json:
               schema:
-            $ref: "../client-server/definitions/public_rooms_response.yaml"
+                $ref: ../client-server/definitions/public_rooms_response.yaml
     post:
       summary: Gets the public rooms on the server with optional filter.
       description: |-
@@ -81,19 +77,15 @@ paths:
       operationId: queryPublicRooms
       security:
         - signedRequest: []
-      parameters:
+      requestBody:
-        - in: body
+        content:
-          name: body
+          application/json:
-          required: true
-          description: |-
-            Options for which rooms to return, or empty object to use defaults.
             schema:
               type: object
               properties:
                 limit:
                   type: integer
-                description: |-
+                  description: Limit the number of results returned.
-                  Limit the number of results returned.
                 since:
                   type: string
                   description: |-
@@ -103,9 +95,8 @@ paths:
                     rather than via an explicit flag.
                 filter:
                   type: object
-                title: "Filter"
+                  title: Filter
-                description: |-
+                  description: Filter to apply to the results.
-                  Filter to apply to the results.
                   properties:
                     generic_search_term:
                       type: string
@@ -133,31 +124,39 @@ paths:
                   description: |-
                     The specific third-party network/protocol to request from the
                     homeserver. Can only be used if `include_all_networks` is false.
-                example: "irc"
+                  example: irc
               example: {
                 "limit": 10,
                 "filter": {
                   "generic_search_term": "foo",
-                "room_types": [null, "m.space"]
+                  "room_types": [
+                    null,
+                    "m.space"
+                  ]
                 },
                 "include_all_networks": false,
                 "third_party_instance_id": "irc"
               }
+        description: Options for which rooms to return, or empty object to use defaults.
+        required: true
       responses:
-        200:
+        "200":
           description: A list of the rooms on the server.
+          content:
+            application/json:
               schema:
                 type: object
                 description: A list of the rooms on the server.
-            required: ["chunk"]
+                required:
+                  - chunk
                 properties:
                   chunk:
-                title: "PublicRoomsChunks"
+                    title: PublicRoomsChunks
                     type: array
                     description: A paginated chunk of public rooms.
                     items:
                       allOf:
-                    - $ref: "../client-server/definitions/public_rooms_chunk.yaml"
+                        - $ref: ../client-server/definitions/public_rooms_chunk.yaml
                         - type: object
                           properties:
                             # Override description of join_rule
@@ -186,7 +185,8 @@ paths:
                       An estimate on the total number of public rooms, if the
                       server has an estimate.
               examples:
-            application/json: {
+                response:
+                  value: {
                     "chunk": [
                       {
                         "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE",
@@ -204,3 +204,18 @@ paths:
                     "prev_batch": "p1902",
                     "total_room_count_estimate": 115
                   }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/federation/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml

data/api/server-server/query.yaml

@@ -12,19 +12,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.
-
+openapi: 3.1.0
-swagger: '2.0'
 info:
-  title: "Matrix Federation Query API"
+  title: Matrix Federation Query API
-  version: "1.0.0"
+  version: 1.0.0
-host: localhost:8448
-schemes:
-  - https
-basePath: /_matrix/federation/v1
-produces:
-  - application/json
-securityDefinitions:
-  $ref: definitions/security.yaml
 paths:
   "/query/{queryType}":
     get:
@@ -39,15 +30,16 @@ paths:
       parameters:
         - in: path
           name: queryType
-          type: string
           description: The type of query to make
           required: true
-          x-example: profile
+          example: profile
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description: |-
+          description: The query response. The schema varies depending on the query being
-            The query response. The schema varies depending on the query being made.
+            made.
-  "/query/directory":
+  /query/directory:
     get:
       summary: Query for the room ID and resident homeservers for a room alias
       description: |-
@@ -63,21 +55,24 @@ paths:
       parameters:
         - in: query
           name: room_alias
-          type: string
           description: The room alias to query.
           required: true
-          x-example: "#room_alias:example.org"
+          example: "#room_alias:example.org"
+          schema:
+            type: string
       responses:
-        200:
+        "200":
-          description: |-
+          description: The corresponding room ID and list of known resident homeservers
-            The corresponding room ID and list of known resident homeservers for the room.
+            for the room.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
                   room_id:
                     type: string
                     description: The room ID mapped to the queried room alias.
-                x-example: "!roomid1234:example.org"
+                    example: "!roomid1234:example.org"
                   servers:
                     type: array
                     description: |-
@@ -86,27 +81,31 @@ paths:
                     items:
                       type: string
                 required:
-              - "room_id"
+                  - room_id
-              - "servers"
+                  - servers
               examples:
-            application/json: {
+                response:
+                  value: {
                     "room_id": "!roomid1234:example.org",
                     "servers": [
                       "example.org",
                       "example.com",
-                "another.example.com:8449",
+                      "another.example.com:8449"
                     ]
                   }
-        404:
+        "404":
           description: The room alias was not found.
+          content:
+            application/json:
               schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "Room alias not found."
                   }
-  "/query/profile":
+  /query/profile:
     get:
       summary: Query for profile information about a given user
       description: |-
@@ -122,20 +121,24 @@ paths:
       parameters:
         - in: query
           name: user_id
-          type: string
           description: The user ID to query.
           required: true
-          x-example: "@someone:example.org"
+          example: "@someone:example.org"
+          schema:
+            type: string
         - in: query
           name: field
-          type: string
-          enum: ['displayname', 'avatar_url']
           description: |-
             The field to query. If specified, the server will only return the given field
             in the response. If not specified, the server will return the full profile for
             the user.
+          schema:
+            type: string
+            enum:
+              - displayname
+              - avatar_url
       responses:
-        200:
+        "200":
           description: |-
             The profile for the user. If a `field` is specified in the request, only the
             matching field should be included in the response. If no `field` was specified,
@@ -144,6 +147,8 @@ paths:
 
             If the user does not have a particular field set on their profile, the server
             should exclude it from the response body or give it the value `null`.
+          content:
+            application/json:
               schema:
                 type: object
                 properties:
@@ -152,24 +157,43 @@ paths:
                     description: |-
                       The display name of the user. May be omitted if the user does not have a
                       display name set.
-                x-example: "John Doe"
+                    example: John Doe
                   avatar_url:
                     type: string
                     description: |-
                       The avatar URL for the user's avatar. May be omitted if the user does not
                       have an avatar set.
-                x-example: "mxc://matrix.org/MyC00lAvatar"
+                    example: mxc://matrix.org/MyC00lAvatar
               examples:
-            application/json: {
+                response:
+                  value: {
                     "displayname": "John Doe",
                     "avatar_url": "mxc://matrix.org/MyC00lAvatar"
                   }
-        404:
+        "404":
           description: The user does not exist or does not have a profile.
+          content:
+            application/json:
               schema:
-            $ref: "../client-server/definitions/errors/error.yaml"
+                $ref: ../client-server/definitions/errors/error.yaml
               examples:
-            application/json: {
+                response:
+                  value: {
                     "errcode": "M_NOT_FOUND",
                     "error": "User does not exist."
                   }
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8448
+      basePath:
+        default: /_matrix/federation/v1
+components:
+  securitySchemes:
+    $ref: definitions/security.yaml