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

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

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/

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