Merge pull request #178 from matrix-org/daniel/directory

Fix and include /directory api docs

api/client-server/v1/directory.yaml

@@ -29,6 +29,7 @@ paths:
           name: roomAlias
           description: The room alias to set.
           required: true
+          x-example: "#monkeys:matrix.org"
         - in: body
           name: roomInfo
           description: Information about this room alias.
@@ -39,11 +40,18 @@ paths:
               room_id:
                 type: string
                 description: The room ID to set.
+            example: |-
+              {
+                "room_id": "!abnjk1jdasj98:capuchins.com"
+              }
       responses:
         200:
           description: The mapping was created.
+          examples:
+            application/json: |-
+              {}
           schema:
-            type: object  # empty json object
+            type: object
     get:
       summary: Get the room ID corresponding to this room alias.
       parameters:
@@ -52,6 +60,7 @@ paths:
           name: roomAlias
           description: The room alias.
           required: true
+          x-example: "#monkeys:matrix.org"
       responses:
         200:
           description: The room ID and other information for this alias.
@@ -67,10 +76,38 @@ paths:
                 items:
                   type: string
                   description: A server which is aware of this room ID.
+          examples:
+            application/json: |-
+              {
+                "room_id": "!abnjk1jdasj98:capuchins.com",
+                "servers": [
+                  "capuchins.com",
+                  "matrix.org",
+                  "another.com"
+                ]
+              }
         404:
           description: There is no mapped room ID for this room alias.
+          examples:
+            application/json: |-
+              {
+                "errcode": "M_NOT_FOUND",
+                "error": "Room ID !abnjk1jdasj98:capuchins.com not found."
+              }
+        409:
+          description: A room alias with that name already exists.
+          examples:
+            application/json: |-
+              {
+                "errcode": "M_UNKNOWN",
+                "error": "Room alias #monkeys:matrix.org already exists."
+              }
     delete:
       summary: Remove a mapping of room alias to room ID.
+      description: |-
+        Remove a mapping of room alias to room ID.
+
+        Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator.
       security:
         - accessToken: []
       parameters:
@@ -79,9 +116,12 @@ paths:
           name: roomAlias
           description: The room alias to remove.
           required: true
+          x-example: "#monkeys:matrix.org"
       responses:
         200:
-          description: The mapping was removed.
+          description: The mapping was deleted.
+          examples:
+            application/json: |-
+              {}
           schema:
-            type: object  # empty json object
-
+            type: object