Merge pull request #3101 from matrix-org/travis/spec/MSC2320-identity-versions

Add identity service versions API

changelogs/identity_service/newsfragments/3101.new

@@ -0,0 +1 @@
+Add `GET /_matrix/identity/versions` API as per [MSC2320](https://github.com/matrix-org/matrix-doc/pull/2320).

content/identity-service-api.md

@@ -103,6 +103,8 @@ the third party identifier.
 `M_UNKNOWN`  
 An unknown error has occurred.
 
+{{% http-api spec="identity" api="versions" %}}
+
 ## Privacy
 
 Identity is a privacy-sensitive issue. While the identity server exists

data/api/identity/versions.yaml

@@ -0,0 +1,51 @@
+# Copyright 2021 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Identity Service Versions API"
+  version: "1.0.0"
+host: localhost:8090
+schemes:
+  - https
+basePath: /_matrix/identity
+produces:
+  - application/json
+paths:
+  "/versions":
+    get:
+      summary: Gets the versions of the specification supported by the server.
+      description: |-
+        Gets the versions of the specification supported by the server.
+
+        Values will take the form `rX.Y.Z`. <!-- TODO: TravisR: Global versioning spec -->
+
+        All supported versions, including patch versions, are reported by the server.
+      operationId: getVersions
+      responses:
+        200:
+          description: The versions supported by the server.
+          examples:
+            application/json: {
+              "versions": ["r0.1.0", "r0.2.0", "r0.2.1"]
+            }
+          schema:
+            type: object
+            properties:
+              versions:
+                type: array
+                description: The supported versions.
+                items:
+                  type: string
+                  description: The supported versions.
+            required: ['versions']