Script to serve the generated swagger JSON

We need custom CORS headers to serve the swagger JSON, so add a script to do it
pull/977/head
Richard van der Hoff 8 years ago
parent c39d797cce
commit 60f36bf868

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

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

@ -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()
Loading…
Cancel
Save