Generate swagger-ui output for client-server API

Depends on:
https://github.com/matrix-org/matrix-doc/pull/212
https://github.com/matrix-org/matrix-doc/pull/208
https://github.com/matrix-org/matrix-doc/pull/207
for the actual rendered output to not throw javascript errors at runtime.

api/client-server/account-data.yaml

@@ -57,6 +57,8 @@ paths:
         200:
           description:
             The account_data was successfully added.
+      tags:
+        - User data
   "/user/{userId}/rooms/{roomId}/account_data/{type}":
     put:
       summary: Set some account_data for the user.
@@ -103,3 +105,5 @@ paths:
         200:
           description:
             The account_data was successfully added.
+      tags:
+        - User data

api/client-server/admin.yaml

@@ -101,3 +101,5 @@ paths:
                                 user_agent:
                                   type: string
                                   description: User agent string last seen in the session.
+      tags:
+        - Server administration

api/client-server/administrative_contact.yaml

@@ -54,6 +54,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - User data
   "/account/3pid":
     get:
       summary: Gets a list of a user's third party identifiers.
@@ -97,6 +99,8 @@ paths:
                     address:
                       type: string
                       description: The third party identifier address.
+      tags:
+        - User data
     post:
       summary: Adds contact information to the user's account.
       description: Adds contact information to the user's account.
@@ -155,3 +159,5 @@ paths:
                 "errcode": "M_THREEPID_AUTH_FAILED",
                 "error": "The third party credentials could not be verified by the identity server."
               }
+      tags:
+        - User data

api/client-server/banning.yaml

@@ -74,3 +74,5 @@ paths:
                 "errcode": "M_FORBIDDEN",
                 "error": "You do not have a high enough power level to ban from this room."
               }
+      tags:
+        - Room membership

api/client-server/content-repo.yaml

@@ -43,6 +43,8 @@ paths:
               {
                 "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
               }
+      tags:
+        - Media
   "/download/{serverName}/{mediaId}":
     get:
       summary: "Download content from the content repository."
@@ -74,6 +76,8 @@ paths:
               type: "string"
           schema:
             type: file
+      tags:
+        - Media
   "/thumbnail/{serverName}/{mediaId}":
     get:
       summary: "Download a thumbnail of the content from the content repository."
@@ -123,5 +127,5 @@ paths:
               enum: ["image/jpeg", "image/png"]
           schema:
             type: file
-            
+      tags:
-
+        - Media

api/client-server/create_room.yaml

@@ -146,3 +146,5 @@ paths:
         400:
           description: >
             The request body is malformed or the room alias specified is already taken.
+      tags:
+        - Room creation

api/client-server/directory.yaml

@@ -52,6 +52,8 @@ paths:
               {}
           schema:
             type: object
+      tags:
+        - Room directory
     get:
       summary: Get the room ID corresponding to this room alias.
       parameters:
@@ -102,6 +104,8 @@ paths:
                 "errcode": "M_UNKNOWN",
                 "error": "Room alias #monkeys:matrix.org already exists."
               }
+      tags:
+        - Room directory
     delete:
       summary: Remove a mapping of room alias to room ID.
       description: |-
@@ -125,3 +129,5 @@ paths:
               {}
           schema:
             type: object
+      tags:
+        - Room directory

api/client-server/filter.yaml

@@ -84,6 +84,8 @@ paths:
                 type: string
                 description: |-
                   The ID of the filter that was created.
+      tags:
+        - Room participation
   "/user/{userId}/filter/{filterId}":
     get:
       summary: Download a filter
@@ -137,3 +139,5 @@ paths:
             type: object
             allOf:
               - $ref: "definitions/sync_filter.json"
+      tags:
+        - Room participation

api/client-server/guest_events.yaml

@@ -101,3 +101,4 @@ paths:
                     - "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
         400:
           description: "Bad pagination ``from`` parameter."
+        # No tags to exclude this from the swagger UI - use the non-guest version instead.

api/client-server/inviting.yaml

@@ -88,3 +88,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership

api/client-server/joining.yaml

@@ -66,3 +66,5 @@ paths:
         canonical-link: "post-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-join"
         aliases:
           - /_matrix/client/%CLIENT_MAJOR_VERSION%/join/{roomId}
+      tags:
+        - Room membership

api/client-server/leaving.yaml

@@ -55,6 +55,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership
   "/rooms/{roomId}/forget":
     post:
       summary: Stop the requesting user remembering about a particular room.
@@ -90,3 +92,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership

api/client-server/list_public_rooms.yaml

@@ -95,3 +95,5 @@ paths:
         400:
           description: >
             The request body is malformed or the room alias specified is already taken.
+      tags:
+        - Room discovery

api/client-server/login.yaml

@@ -101,6 +101,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Session management
   "/tokenrefresh":
     post:
       summary: Exchanges a refresh token for an access token.
@@ -158,3 +160,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Session management

api/client-server/message_pagination.yaml

@@ -129,3 +129,5 @@ paths:
         403:
           description: >
             You aren't a member of the room.
+      tags:
+        - Room participation

api/client-server/old_sync.yaml

@@ -87,6 +87,8 @@ paths:
                     - "$ref": "../../event-schemas/schema/core-event-schema/room_event.json"
         400:
           description: "Bad pagination ``from`` parameter."
+      tags:
+        - Room participation
   "/initialSync":
     get:
       summary: Get the user's current state.
@@ -365,6 +367,8 @@ paths:
             required: ["end", "rooms", "presence"]
         404:
           description: There is no avatar URL for this user or this user does not exist.
+      tags:
+        - Room participation
   "/events/{eventId}":
     get:
       summary: Get a single event by event ID.
@@ -400,3 +404,5 @@ paths:
               - "$ref": "../../event-schemas/schema/core-event-schema/event.json"
         404:
           description: The event was not found or you do not have permission to read this event.
+      tags:
+        - Room participation

api/client-server/presence.yaml

@@ -67,6 +67,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Presence
     get:
       summary: Get this user's presence state.
       description: |-
@@ -106,6 +108,8 @@ paths:
           description: |-
             There is no presence state for this user. This user may not exist or
             isn't exposing presence information to you.
+      tags:
+        - Presence
   "/presence/list/{userId}":
     post:
       summary: Add or remove users from this presence list.
@@ -160,6 +164,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Presence
     get:
       summary: Get presence events for this presence list.
       description: |-
@@ -205,3 +211,5 @@ paths:
               title: PresenceEvent
               allOf:
                 - "$ref": "../../event-schemas/schema/core-event-schema/event.json"
+      tags:
+        - Presence

api/client-server/profile.yaml

@@ -59,6 +59,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - User data
     get:
       summary: Get the user's display name.
       description: |-
@@ -88,6 +90,8 @@ paths:
                 description: The user's display name if they have set one.
         404:
           description: There is no display name for this user or this user does not exist.
+      tags:
+        - User data
   "/profile/{userId}/avatar_url":
     put:
       summary: Set the user's avatar URL.
@@ -129,6 +133,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - User data
     get:
       summary: Get the user's avatar URL.
       description: |-
@@ -158,6 +164,8 @@ paths:
                 description: The user's avatar URL if they have set one.
         404:
           description: There is no avatar URL for this user or this user does not exist.
+      tags:
+        - User data
   "/profile/{userId}":
     get:
       summary: Get this user's profile information.
@@ -192,4 +200,6 @@ paths:
                 type: string
                 description: The user's display name if they have set one.
         404:
-          description: There is no profile information for this user or this user does not exist.
+          description: There is no profile information for this user or this user does not exist.
+      tags:
+        - User data

api/client-server/push_notifier.yaml

@@ -189,4 +189,5 @@ paths:
                 items:
                   type: string
                   description: A pushkey
-
+      tags:
+        - Push notifications

api/client-server/pusher.yaml

@@ -60,7 +60,6 @@ paths:
                   Max length, 512 bytes.
               kind:
                 type: string
-                enum: ["http", null]
                 description: |-
                   The kind of pusher to configure. ``"http"`` makes a pusher that
                   sends HTTP pokes. ``null`` deletes the pusher.
@@ -141,4 +140,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
-
+      tags:
+        - Push notifications

api/client-server/pushrules.yaml

@@ -245,6 +245,8 @@ paths:
                     ]
                 }
               }
+      tags:
+        - Push notifications
   "/pushrules/{scope}/{kind}/{ruleId}":
     get:
       summary: Retrieve a push rule.
@@ -297,6 +299,8 @@ paths:
             allOf: [
               "$ref": "definitions/push_rule.json"
             ]
+      tags:
+        - Push notifications
     delete:
       summary: Delete a push rule.
       description: |-
@@ -335,6 +339,8 @@ paths:
               {}
           schema:
             type: object  # empty json object
+      tags:
+        - Push notifications
     put:
       summary: Add or change a push rule.
       description: |-
@@ -438,6 +444,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Push notifications
   "/pushrules/{scope}/{kind}/{ruleId}/enabled":
     put:
       summary: "Enable or disable a push rule."
@@ -492,4 +500,6 @@ paths:
             application/json: |-
               {}
           schema:
-            type: object  # empty json object
+            type: object
+      tags:
+        - Push notifications

api/client-server/receipts.yaml

@@ -67,3 +67,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Room participation

api/client-server/redaction.yaml

@@ -80,3 +80,5 @@ paths:
                 type: string
                 description: |-
                   A unique identifier for the event.
+      tags:
+        - Room participation

api/client-server/registration.yaml

@@ -121,3 +121,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - User data

api/client-server/room_send.yaml

@@ -76,3 +76,5 @@ paths:
                 type: string
                 description: |-
                   A unique identifier for the event.
+      tags:
+        - Room participation

api/client-server/room_state.yaml

@@ -78,6 +78,8 @@ paths:
                 type: string
                 description: |-
                   A unique identifier for the event.
+      tags:
+        - Room participation
   "/rooms/{roomId}/state/{eventType}":
     put:
       summary: Send a state event to the given room.
@@ -131,3 +133,5 @@ paths:
                 type: string
                 description: |-
                   A unique identifier for the event.
+      tags:
+        - Room participation

api/client-server/rooms.yaml

@@ -61,7 +61,8 @@ paths:
           description: >
             You aren't a member of the room and weren't previously a
             member of the room.
-
+      tags:
+        - Room participation
   "/rooms/{roomId}/state/{eventType}":
     get:
       summary: Get the state identified by the type, with the empty state key.
@@ -101,8 +102,8 @@ paths:
           description: >
             You aren't a member of the room and weren't previously a
             member of the room.
-
+      tags:
-
+        - Room participation
   "/rooms/{roomId}/state":
     get:
       summary: Get all state events in the current state of a room.
@@ -218,7 +219,8 @@ paths:
           description: >
             You aren't a member of the room and weren't previously a
             member of the room.
-
+      tags:
+        - Room participation
   "/rooms/{roomId}/initialSync":
     get:
       summary: Snapshot the current state of a room and its most recent messages.
@@ -428,7 +430,8 @@ paths:
           description: >
             You aren't a member of the room and weren't previously a
             member of the room.
-
+      tags:
+        - Room participation
   "/rooms/{roomId}/members":
     get:
       summary: Get the m.room.member events for the room.
@@ -496,4 +499,5 @@ paths:
           description: >
             You aren't a member of the room and weren't previously a
             member of the room.
-
+      tags:
+        - Room participation

api/client-server/search.yaml

@@ -144,3 +144,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Search

api/client-server/sync.yaml

@@ -310,3 +310,5 @@ paths:
                   "leave": {}
                 }
               }
+      tags:
+        - Room participation

api/client-server/tags.yaml

@@ -59,6 +59,8 @@ paths:
                   "pinned": {}
                 }
               }
+      tags:
+        - User data
   "/user/{userId}/rooms/{roomId}/tags/{tag}":
     put:
       summary: Add a tag to a room.
@@ -107,6 +109,8 @@ paths:
           examples:
             application/json: |-
               {}
+      tags:
+        - User data
     delete:
       summary: Remove a tag from the room.
       description: |-
@@ -145,3 +149,5 @@ paths:
           examples:
             application/json: |-
               {}
+      tags:
+        - User data

api/client-server/third_party_membership.yaml

@@ -121,3 +121,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership

api/client-server/typing.yaml

@@ -74,4 +74,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
-
+      tags:
+        - Room participation

api/client-server/voip.yaml

@@ -65,4 +65,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
-
+      tags:
+        - VOIP

scripts/add-matrix-org-stylings.sh

@@ -22,7 +22,7 @@ perl -MFile::Slurp -pi -e 'BEGIN { $header = read_file("'$HEADER'") } s#<head>#<
   <link rel="stylesheet" href="//matrix.org/docs/guides/css/docs_overrides.css">
 #' ${files}
 
-perl -MFile::Slurp -pi -e 'BEGIN { $nav = read_file("'$NAV_BAR'") } s#<body>#  <body class="blog et_fixed_nav et_cover_background et_right_sidebar">
+perl -MFile::Slurp -pi -e 'BEGIN { $nav = read_file("'$NAV_BAR'") } s#<body class="swagger-section">#  <body class=" swagger-section blog et_fixed_nav et_cover_background et_right_sidebar">
    <div id="page-wrapper">
     <div class="page-content" id="page-container">
       $nav

scripts/dump-swagger.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python2
+
+# dump-swagger reads all of the swagger API docs used in spec generation and
+# outputs a JSON file which merges them all, for use as input to a swagger UI
+# viewer.
+# See https://github.com/swagger-api/swagger-ui for details of swagger-ui.
+
+import errno
+import json
+import os.path
+import re
+import shutil
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "templating"))
+from matrix_templates.units import resolve_references, MatrixUnits
+
+if len(sys.argv) < 2 or len(sys.argv) > 3:
+    sys.stderr.write("usage: %s output_directory [client_release_label]\n" % (sys.argv[0],))
+    sys.exit(1)
+
+output_directory = sys.argv[1]
+release_label = sys.argv[2] if len(sys.argv) > 2 else "unstable"
+
+major_version = release_label
+match = re.match("^(r\d)+(\.\d+)?$", major_version)
+if match:
+    major_version = match.group(1)
+
+apis = MatrixUnits().load_swagger_apis()
+
+output = {
+    "basePath": "/matrix/client/" + major_version,
+    "consumes": ["application/json"],
+    "produces": ["application/json"],
+    "host": "localhost:8008",
+    "info": {
+        "title": "Matrix Client-Server API",
+        "version": release_label,
+    },
+    "paths": {},
+    "swagger": "2.0",
+}
+
+for file, contents in apis.items():
+    for path, methods in contents["paths"].items():
+        for method, spec in methods.items():
+            if "tags" in spec.keys():
+                if path not in output["paths"]:
+                    output["paths"][path] = {}
+                output["paths"][path][method] = spec
+
+path = os.path.join(output_directory, "api-docs")
+try:
+    os.makedirs(os.path.dirname(path))
+except OSError as e:
+    if e.errno != errno.EEXIST:
+        raise
+
+with open(path, "w") as f:
+    text = json.dumps(output, sort_keys=True, indent=4)
+    text = text.replace("%CLIENT_RELEASE_LABEL%", release_label)
+    text = text.replace("%CLIENT_MAJOR_VERSION%", major_version)
+    f.write(text)

scripts/generate-http-docs.sh

@@ -1,38 +0,0 @@
-#!/bin/bash -eu
-
-# This script generates an HTML page containing all of the client-server API docs.
-# It takes all of the swagger YAML files for the client-server API, and turns
-# them into API docs, with none of the narrative found in the rst files which
-# normally wrap these API docs.
-#
-# Optionally takes one positional argument, the label of the release, e.g. r1.2.
-# This falls back to "unstable" if unspecified.
-
-if [[ $# == 1 ]]; then
-  client_release=$1
-else
-  client_release="unstable"
-fi
-
-client_major_version="$(echo "${client_release}" | perl -pe 's/^(r\d+)\..*$/$1/g')"
-
-cd "$(dirname $0)"
-
-mkdir -p tmp gen
-
-cat >tmp/http_apis <<EOF
-Matrix Client-Server API Reference
-==================================
-
-This contains the client-server API for the reference implementation of the homeserver.
-
-
-EOF
-
-for f in ../api/client-server/*.yaml; do
-  f="$(basename "${f/.yaml/_http_api}")"
-  echo "{{${f/-/_}}}" >> tmp/http_apis
-done
-
-(cd ../templating ; python build.py -i matrix_templates -o ../scripts/gen ../scripts/tmp/http_apis --substitution=%CLIENT_RELEASE_LABEL%="${client_release}" --substitution=%CLIENT_MAJOR_VERSION%="${client_major_version}")
-rst2html.py --stylesheet-path=$(echo css/*.css | tr ' ' ',') gen/http_apis > gen/http_apis.html