From 1f5b6271f220e01fd5069fabbc2f0bc0951971fd Mon Sep 17 00:00:00 2001 From: Daniel Wagner-Hall Date: Mon, 7 Dec 2015 12:45:13 +0000 Subject: [PATCH] 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 | 4 ++ api/client-server/admin.yaml | 2 + api/client-server/administrative_contact.yaml | 6 ++ api/client-server/banning.yaml | 2 + api/client-server/content-repo.yaml | 8 ++- api/client-server/create_room.yaml | 2 + api/client-server/directory.yaml | 6 ++ api/client-server/filter.yaml | 4 ++ api/client-server/guest_events.yaml | 1 + api/client-server/inviting.yaml | 2 + api/client-server/joining.yaml | 2 + api/client-server/leaving.yaml | 4 ++ api/client-server/list_public_rooms.yaml | 2 + api/client-server/login.yaml | 4 ++ api/client-server/message_pagination.yaml | 2 + api/client-server/old_sync.yaml | 6 ++ api/client-server/presence.yaml | 8 +++ api/client-server/profile.yaml | 12 +++- api/client-server/push_notifier.yaml | 3 +- api/client-server/pusher.yaml | 4 +- api/client-server/pushrules.yaml | 12 +++- api/client-server/receipts.yaml | 2 + api/client-server/redaction.yaml | 2 + api/client-server/registration.yaml | 2 + api/client-server/room_send.yaml | 2 + api/client-server/room_state.yaml | 4 ++ api/client-server/rooms.yaml | 16 +++-- api/client-server/search.yaml | 2 + api/client-server/sync.yaml | 2 + api/client-server/tags.yaml | 6 ++ api/client-server/third_party_membership.yaml | 2 + api/client-server/typing.yaml | 3 +- api/client-server/voip.yaml | 3 +- scripts/add-matrix-org-stylings.sh | 2 +- scripts/dump-swagger.py | 64 +++++++++++++++++++ scripts/generate-http-docs.sh | 38 ----------- 36 files changed, 192 insertions(+), 54 deletions(-) create mode 100755 scripts/dump-swagger.py delete mode 100755 scripts/generate-http-docs.sh diff --git a/api/client-server/account-data.yaml b/api/client-server/account-data.yaml index 111099d5..5921dc29 100644 --- a/api/client-server/account-data.yaml +++ b/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 diff --git a/api/client-server/admin.yaml b/api/client-server/admin.yaml index 06926b3a..349dfbf4 100644 --- a/api/client-server/admin.yaml +++ b/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 diff --git a/api/client-server/administrative_contact.yaml b/api/client-server/administrative_contact.yaml index 8162c4c9..8c8e0a35 100644 --- a/api/client-server/administrative_contact.yaml +++ b/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 diff --git a/api/client-server/banning.yaml b/api/client-server/banning.yaml index f4f4b15b..ad0e2834 100644 --- a/api/client-server/banning.yaml +++ b/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 diff --git a/api/client-server/content-repo.yaml b/api/client-server/content-repo.yaml index 34194952..7a44b866 100644 --- a/api/client-server/content-repo.yaml +++ b/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 diff --git a/api/client-server/create_room.yaml b/api/client-server/create_room.yaml index 60f9599d..6e19b1d8 100644 --- a/api/client-server/create_room.yaml +++ b/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 diff --git a/api/client-server/directory.yaml b/api/client-server/directory.yaml index 7b3cc889..773706a7 100644 --- a/api/client-server/directory.yaml +++ b/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 diff --git a/api/client-server/filter.yaml b/api/client-server/filter.yaml index e8ef3e70..4dd0b597 100644 --- a/api/client-server/filter.yaml +++ b/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 diff --git a/api/client-server/guest_events.yaml b/api/client-server/guest_events.yaml index 85f5c6b7..ff02d1fb 100644 --- a/api/client-server/guest_events.yaml +++ b/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. diff --git a/api/client-server/inviting.yaml b/api/client-server/inviting.yaml index 7bc703c7..1dd7de5f 100644 --- a/api/client-server/inviting.yaml +++ b/api/client-server/inviting.yaml @@ -88,3 +88,5 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" + tags: + - Room membership diff --git a/api/client-server/joining.yaml b/api/client-server/joining.yaml index 530fa1b6..23bdc6a5 100644 --- a/api/client-server/joining.yaml +++ b/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 diff --git a/api/client-server/leaving.yaml b/api/client-server/leaving.yaml index 36a375fe..95a2133a 100644 --- a/api/client-server/leaving.yaml +++ b/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 diff --git a/api/client-server/list_public_rooms.yaml b/api/client-server/list_public_rooms.yaml index c1c83093..ad7dfca9 100644 --- a/api/client-server/list_public_rooms.yaml +++ b/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 diff --git a/api/client-server/login.yaml b/api/client-server/login.yaml index 2335dcb7..b9aa0596 100644 --- a/api/client-server/login.yaml +++ b/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 diff --git a/api/client-server/message_pagination.yaml b/api/client-server/message_pagination.yaml index 40c4c754..b1d4cfb7 100644 --- a/api/client-server/message_pagination.yaml +++ b/api/client-server/message_pagination.yaml @@ -129,3 +129,5 @@ paths: 403: description: > You aren't a member of the room. + tags: + - Room participation diff --git a/api/client-server/old_sync.yaml b/api/client-server/old_sync.yaml index bdbf64b9..3dff7a78 100644 --- a/api/client-server/old_sync.yaml +++ b/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 diff --git a/api/client-server/presence.yaml b/api/client-server/presence.yaml index 81272711..23edc4e2 100644 --- a/api/client-server/presence.yaml +++ b/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 diff --git a/api/client-server/profile.yaml b/api/client-server/profile.yaml index ccdccc25..2791714d 100644 --- a/api/client-server/profile.yaml +++ b/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. \ No newline at end of file + description: There is no profile information for this user or this user does not exist. + tags: + - User data diff --git a/api/client-server/push_notifier.yaml b/api/client-server/push_notifier.yaml index 420d4183..271597d8 100644 --- a/api/client-server/push_notifier.yaml +++ b/api/client-server/push_notifier.yaml @@ -189,4 +189,5 @@ paths: items: type: string description: A pushkey - + tags: + - Push notifications diff --git a/api/client-server/pusher.yaml b/api/client-server/pusher.yaml index 6426618a..d8566053 100644 --- a/api/client-server/pusher.yaml +++ b/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 diff --git a/api/client-server/pushrules.yaml b/api/client-server/pushrules.yaml index 475160bd..a00ca2e8 100644 --- a/api/client-server/pushrules.yaml +++ b/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 diff --git a/api/client-server/receipts.yaml b/api/client-server/receipts.yaml index d3e65e09..791e3938 100644 --- a/api/client-server/receipts.yaml +++ b/api/client-server/receipts.yaml @@ -67,3 +67,5 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" + tags: + - Room participation diff --git a/api/client-server/redaction.yaml b/api/client-server/redaction.yaml index d30ef8c1..91948b2b 100644 --- a/api/client-server/redaction.yaml +++ b/api/client-server/redaction.yaml @@ -80,3 +80,5 @@ paths: type: string description: |- A unique identifier for the event. + tags: + - Room participation diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index df6cafe4..fe57f950 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -121,3 +121,5 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" + tags: + - User data diff --git a/api/client-server/room_send.yaml b/api/client-server/room_send.yaml index dad54353..70d005c2 100644 --- a/api/client-server/room_send.yaml +++ b/api/client-server/room_send.yaml @@ -76,3 +76,5 @@ paths: type: string description: |- A unique identifier for the event. + tags: + - Room participation diff --git a/api/client-server/room_state.yaml b/api/client-server/room_state.yaml index f2464fe7..e28dfde4 100644 --- a/api/client-server/room_state.yaml +++ b/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 diff --git a/api/client-server/rooms.yaml b/api/client-server/rooms.yaml index 0d2a99b2..68e7b993 100644 --- a/api/client-server/rooms.yaml +++ b/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 diff --git a/api/client-server/search.yaml b/api/client-server/search.yaml index 66285f1d..da2fcec6 100644 --- a/api/client-server/search.yaml +++ b/api/client-server/search.yaml @@ -144,3 +144,5 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" + tags: + - Search diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml index b9c20045..d3ae9fd0 100644 --- a/api/client-server/sync.yaml +++ b/api/client-server/sync.yaml @@ -310,3 +310,5 @@ paths: "leave": {} } } + tags: + - Room participation diff --git a/api/client-server/tags.yaml b/api/client-server/tags.yaml index 76201034..404ed7ef 100644 --- a/api/client-server/tags.yaml +++ b/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 diff --git a/api/client-server/third_party_membership.yaml b/api/client-server/third_party_membership.yaml index 80065be9..da3d4160 100644 --- a/api/client-server/third_party_membership.yaml +++ b/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 diff --git a/api/client-server/typing.yaml b/api/client-server/typing.yaml index 65e0634a..02ad0efd 100644 --- a/api/client-server/typing.yaml +++ b/api/client-server/typing.yaml @@ -74,4 +74,5 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" - + tags: + - Room participation diff --git a/api/client-server/voip.yaml b/api/client-server/voip.yaml index 983cfe93..bdeeaa8d 100644 --- a/api/client-server/voip.yaml +++ b/api/client-server/voip.yaml @@ -65,4 +65,5 @@ paths: description: This request was rate-limited. schema: "$ref": "definitions/error.yaml" - + tags: + - VOIP diff --git a/scripts/add-matrix-org-stylings.sh b/scripts/add-matrix-org-stylings.sh index 9a9256b2..b134502c 100755 --- a/scripts/add-matrix-org-stylings.sh +++ b/scripts/add-matrix-org-stylings.sh @@ -22,7 +22,7 @@ perl -MFile::Slurp -pi -e 'BEGIN { $header = read_file("'$HEADER'") } s##< #' ${files} -perl -MFile::Slurp -pi -e 'BEGIN { $nav = read_file("'$NAV_BAR'") } s## +perl -MFile::Slurp -pi -e 'BEGIN { $nav = read_file("'$NAV_BAR'") } s##
$nav diff --git a/scripts/dump-swagger.py b/scripts/dump-swagger.py new file mode 100755 index 00000000..7b111502 --- /dev/null +++ b/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) diff --git a/scripts/generate-http-docs.sh b/scripts/generate-http-docs.sh deleted file mode 100755 index 41a65296..00000000 --- a/scripts/generate-http-docs.sh +++ /dev/null @@ -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 <> 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