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