Document the /publicRooms endpoint for federation

This intentionally doesn't document the third party network aspect of the endpoint. This is scheduled for a later area for dealing with third party network/IDs and is reported as https://github.com/matrix-org/matrix-doc/issues/1476

The client-server response has been broken out to a shared file: both the client-server and server-server /publicRoom endpoints return the same thing, with slightly different inputs.

The inputs (and behaviour) are based upon the docstring here: 43ecfe0b10/synapse/federation/transport/server.py (L583-L612)

api/server-server/public_rooms.yaml

@@ -0,0 +1,52 @@
+# 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 Public Rooms API"
+  version: "1.0.0"
+host: localhost:8448
+schemes:
+  - https
+basePath: /_matrix/federation/v1
+produces:
+  - application/json
+paths:
+  "/publicRooms":
+    get:
+      summary: Get all the public rooms for a homeserver
+      description: |-
+        Gets all the public rooms for the homeserver. This should not return
+        rooms that are listed on another homeserver's directory, just those
+        listed on the receiving homeserver's directory.
+      operationId: getPublicRooms
+      parameters:
+        - in: query
+          name: limit
+          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"
+      responses:
+        200:
+          description: The public room list for the homeserver.
+          schema:
+            $ref: "../client-server/definitions/public_rooms_response.yaml"