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.pull/977/head
Daniel Wagner-Hall
9 years ago
parent
c9fee294df
commit
1f5b6271f2
@ -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)
|
||||||
@ -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
|
|
||||||
Loading…
Reference in New Issue