wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Generate swagger-ui output for client-server API

Browse source 
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.
This commit is contained in:
Daniel Wagner-Hall 2015-12-07 12:45:13 +00:00
parent c9fee294df
commit 1f5b6271f2
36 changed files with 192 additions and 54 deletions
Download patch file Download diff file Expand all files Collapse all files

4
api/client-server/account-data.yaml
View file

@ -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

2
api/client-server/admin.yaml
View file

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

6
api/client-server/administrative_contact.yaml
View file

@ -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

2
api/client-server/banning.yaml
View file

@ -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

8
api/client-server/content-repo.yaml
View file

@ -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

2
api/client-server/create_room.yaml
View file

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

6
api/client-server/directory.yaml
View file

@ -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

4
api/client-server/filter.yaml
View file

@ -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

1
api/client-server/guest_events.yaml
View file

@ -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.

2
api/client-server/inviting.yaml
View file

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

2
api/client-server/joining.yaml
View file

@ -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

4
api/client-server/leaving.yaml
View file

@ -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

2
api/client-server/list_public_rooms.yaml
View file

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

4
api/client-server/login.yaml
View file

@ -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

2
api/client-server/message_pagination.yaml
View file

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

6
api/client-server/old_sync.yaml
View file

@ -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

8
api/client-server/presence.yaml
View file

@ -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

10
api/client-server/profile.yaml
View file

@ -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.
@ -193,3 +201,5 @@ paths:
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.
tags:
- User data

3
api/client-server/push_notifier.yaml
View file

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

4
api/client-server/pusher.yaml
View file

@ -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

12
api/client-server/pushrules.yaml
View file

@ -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

2
api/client-server/receipts.yaml
View file

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

2
api/client-server/redaction.yaml
View file

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

2
api/client-server/registration.yaml
View file

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

2
api/client-server/room_send.yaml
View file

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

4
api/client-server/room_state.yaml
View file

@ -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

16
api/client-server/rooms.yaml
View file

@ -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

2
api/client-server/search.yaml
View file

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

2
api/client-server/sync.yaml
View file

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

6
api/client-server/tags.yaml
View file

@ -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

2
api/client-server/third_party_membership.yaml
View file

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

3
api/client-server/typing.yaml
View file

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

3
api/client-server/voip.yaml
View file

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

2
scripts/add-matrix-org-stylings.sh
View file

@ -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

64
scripts/dump-swagger.py Executable file
View file

@ -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)

38
scripts/generate-http-docs.sh
View file

@ -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