From 60f36bf868073b0562ad00856781b08836fa2031 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Tue, 3 May 2016 11:52:20 +0100
Subject: [PATCH] Script to serve the generated swagger JSON

We need custom CORS headers to serve the swagger JSON, so add a script to do it
---
 scripts/README                 | 11 ----------
 scripts/README.md              | 39 ++++++++++++++++++++++++++++++++++
 scripts/swagger-http-server.py | 35 ++++++++++++++++++++++++++++++
 3 files changed, 74 insertions(+), 11 deletions(-)
 delete mode 100644 scripts/README
 create mode 100644 scripts/README.md
 create mode 100755 scripts/swagger-http-server.py

diff --git a/scripts/README b/scripts/README
deleted file mode 100644
index a65b8577..00000000
--- a/scripts/README
+++ /dev/null
@@ -1,11 +0,0 @@
-Requirements:
- - docutils (for converting RST to HTML)
- - Jinja2 (for templating)
-
-To generate the complete specification along with supporting documentation, run:
-    python gendoc.py
-
-The output of this will be inside the "gen" folder.
-
-Matrix.org only ("gen" folder has matrix.org tweaked pages):
-    ./matrix-org-gendoc.sh /path/to/matrix.org/includes/nav.html
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 00000000..34cb8845
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,39 @@
+Generating the HTML for the specification
+=========================================
+
+Requirements:
+ - docutils (for converting RST to HTML)
+ - Jinja2 (for templating)
+
+To generate the complete specification along with supporting documentation, run:
+    python gendoc.py
+
+The output of this will be inside the "scripts/gen" folder.
+
+Matrix.org only ("gen" folder has matrix.org tweaked pages):
+    ./matrix-org-gendoc.sh /path/to/matrix.org/includes/nav.html
+
+
+Generating the Swagger documentation
+====================================
+Swagger[1] is a framework for representing RESTful APIs. We use it to generate 
+interactive documentation for our APIs.
+
+Swagger UI reads a JSON description of the API. To generate this file from the
+YAML files in the `api` folder, run:
+    ./dump-swagger.py
+
+By default, `dump-swagger` will write to `scripts/swagger/api-docs.json`.
+
+To make use of the generated file, there are a number of options:
+ * It can be uploaded from your filesystem to an online editor/viewer such as
+   http://editor.swagger.io/
+ * You can run a local HTTP server by running `./swagger-http-server.py`, and
+   then view the documentation via an online viewer; for example, at
+   http://petstore.swagger.io/?url=http://localhost:8000/api-docs.json
+ * You can host the swagger UI yourself:
+   * download the latest release from https://github.com/swagger-api/swagger-ui
+   * copy the contents of the 'dist' directory alongside `api-docs.json`
+   * View the UI via your browser at http://<hostname>?url=api-docs.json
+
+[1] http://swagger.io/
diff --git a/scripts/swagger-http-server.py b/scripts/swagger-http-server.py
new file mode 100755
index 00000000..837ba9c6
--- /dev/null
+++ b/scripts/swagger-http-server.py
@@ -0,0 +1,35 @@
+#!/usr/bin/env python
+#
+# Runs an HTTP server on localhost:8000 which will serve the generated swagger
+# JSON so that it can be viewed in an online swagger UI.
+#
+
+import argparse
+import os
+import SimpleHTTPServer
+import SocketServer
+
+PORT = 8000
+
+# Thanks to http://stackoverflow.com/a/13354482
+class MyHTTPRequestHandler(SimpleHTTPServer.SimpleHTTPRequestHandler):
+    def end_headers(self):
+        self.send_my_headers()
+        SimpleHTTPServer.SimpleHTTPRequestHandler.end_headers(self)
+
+    def send_my_headers(self):
+        self.send_header("Access-Control-Allow-Origin", "*")
+
+
+if __name__ == '__main__':
+    scripts_dir = os.path.dirname(os.path.abspath(__file__))
+    parser = argparse.ArgumentParser()
+    parser.add_argument('swagger_dir', nargs='?',
+                        default=os.path.join(scripts_dir, 'swagger'))
+    args = parser.parse_args()
+
+    os.chdir(args.swagger_dir)
+
+    httpd = SocketServer.TCPServer(("localhost", PORT), MyHTTPRequestHandler)
+    print "Serving at http://localhost:%i/api-docs.json" % PORT
+    httpd.serve_forever()