From d7357ef9b75893631e4a8b1e5e40273885cd6709 Mon Sep 17 00:00:00 2001
From: Daniel Wagner-Hall <daniel@matrix.org>
Date: Wed, 11 Nov 2015 11:39:40 +0000
Subject: [PATCH] Specify /publicRooms

---
 api/client-server/v1/list_public_rooms.yaml   | 85 +++++++++++++++++++
 specification/client_server_api.rst           |  5 ++
 .../matrix_templates/templates/http-api.tmpl  |  5 +-
 3 files changed, 94 insertions(+), 1 deletion(-)
 create mode 100644 api/client-server/v1/list_public_rooms.yaml

diff --git a/api/client-server/v1/list_public_rooms.yaml b/api/client-server/v1/list_public_rooms.yaml
new file mode 100644
index 00000000..2f189d2e
--- /dev/null
+++ b/api/client-server/v1/list_public_rooms.yaml
@@ -0,0 +1,85 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Room Creation API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+paths:
+  "/publicRooms":
+    get:
+      summary: Lists the public rooms on the server.
+      description: |-
+        Lists the public rooms on the server.
+
+        This API returns paginated responses.
+      responses:
+        200:
+          description: A list of the rooms on the server.
+          schema:
+            type: object
+            description: A list of the rooms on the server.
+            properties:
+              chunk:
+                title: "PublicRoomsChunks"
+                type: array
+                description: |-
+                  A paginated chunk of public rooms.
+                items:
+                  type: object
+                  title: "PublicRoomsChunk"
+                  properties:
+                    aliases:
+                      type: array
+                      description: |-
+                        Aliases of the room. May be empty.
+                      items:
+                        type: string
+                    name:
+                      type: string
+                      description: |-
+                        The name of the room, if any. May be null.
+                    num_joined_members:
+                      type: number
+                      description: |-
+                        The number of members joined to the room.
+                    room_id:
+                      type: string
+                      description: |-
+                        The ID of the room.
+                    topic:
+                      type: string
+                      description: |-
+                        The topic of the room, if any. May be null.
+              start:
+                type: string
+                description: |-
+                  A pagination token for the response.
+              end:
+                type: string
+                description: |-
+                  A pagination token for the response.
+          examples:
+            application/json: |-
+              {
+                "chunk": [
+                  {
+                    "aliases": ["#murrays:cheese.bar"],
+                    "name": "CHEESE",
+                    "num_joined_members": 37,
+                    "room_id": "!ol19s:bleecker.street",
+                    "topic": "Tasty tasty cheese"
+                  }
+                ],
+                "start": "p190q",
+                "end": "p1902"
+              }
+        400:
+          description: >
+            The request body is malformed or the room alias specified is already taken.
diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst
index b02dbf28..05b6ff3c 100644
--- a/specification/client_server_api.rst
+++ b/specification/client_server_api.rst
@@ -931,6 +931,11 @@ member's state, by making a request to
     "membership": "ban"
   }
 
+Listing rooms
+~~~~~~~~~~~~~
+
+{{list_public_rooms_http_api}}
+
 Profiles
 --------
 
diff --git a/templating/matrix_templates/templates/http-api.tmpl b/templating/matrix_templates/templates/http-api.tmpl
index 86eacb14..d7258e98 100644
--- a/templating/matrix_templates/templates/http-api.tmpl
+++ b/templating/matrix_templates/templates/http-api.tmpl
@@ -12,7 +12,7 @@
 {{":Requires auth: Yes." if endpoint.requires_auth else "" }}
 
 Request format:
-
+{% if (endpoint.req_param_by_loc | length) %}
 =========================================== ================= ===========================================
    Parameter                                 Value                        Description
 =========================================== ================= ===========================================
@@ -24,6 +24,9 @@ Request format:
 {% endfor -%}
 {% endfor -%}
 =========================================== ================= ===========================================
+{% else %}
+`No parameters`
+{% endif %}
 
 {% if endpoint.res_tables|length > 0 -%}
 Response format: