From 51faf8ed2e4a63d4cfd6d23183698ed169956cc0 Mon Sep 17 00:00:00 2001
From: Travis Ralston <travpc@gmail.com>
Date: Thu, 12 Jul 2018 13:46:42 -0600
Subject: [PATCH] Convert the general query API to swagger

Includes "moving" the directory query API into the same area. This will make more sense once the other query types are specified.
---
 api/server-server/directory.yaml     |  3 +-
 api/server-server/query_general.yaml | 44 ++++++++++++++++++++++++++++
 specification/server_server_api.rst  | 11 +------
 3 files changed, 47 insertions(+), 11 deletions(-)
 create mode 100644 api/server-server/query_general.yaml

diff --git a/api/server-server/directory.yaml b/api/server-server/directory.yaml
index 516b1bf8..94f115b9 100644
--- a/api/server-server/directory.yaml
+++ b/api/server-server/directory.yaml
@@ -1,4 +1,5 @@
 # Copyright 2017 Kamax.io
+# Copyright 2018 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,7 +15,7 @@
 
 swagger: '2.0'
 info:
-  title: "Matrix Federation Query Directory API"
+  title: "Matrix Federation Query API"
   version: "1.0.0"
 host: localhost:8448
 schemes:
diff --git a/api/server-server/query_general.yaml b/api/server-server/query_general.yaml
new file mode 100644
index 00000000..97e3406e
--- /dev/null
+++ b/api/server-server/query_general.yaml
@@ -0,0 +1,44 @@
+# Copyright 2018 New Vector Ltd
+#
+# 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 Federation Query API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+produces:
+  - application/json
+paths:
+  "/query/{queryType}":
+    get:
+      summary: Query for information
+      description: |-
+        Performs a single query request on the receiving homeserver. The query string
+        arguments are dependent on which type of query is being made. Known query types
+        are specified as their own endpoints as an extension to this definition.
+      operationId: queryInfo
+      parameters:
+        - in: path
+          name: queryType
+          type: string
+          description: The type of query to make
+          required: true
+          x-example: profile
+      responses:
+        200:
+          description: |-
+            The query response. The schema varies depending on the query being made.
diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst
index f2b3204a..66c06c8b 100644
--- a/specification/server_server_api.rst
+++ b/specification/server_server_api.rst
@@ -801,16 +801,7 @@ Retrieves all of the transactions later than any version given by the "v"
 arguments.
 
 
-To make a query::
-
-  GET .../query/<query_type>
-    Query args: as specified by the individual query types
-    Response: JSON encoding of a response object
-
-Performs a single query request on the receiving homeserver. The Query Type
-part of the path specifies the kind of query being made, and its query
-arguments have a meaning specific to that kind of query. The response is a
-JSON-encoded object whose meaning also depends on the kind of query.
+{{query_general_ss_http_api}}
 
 
 To join a room::