1320a86cbe
There are a few parts to this: * when we generate the spec for a particular git sha, also run the script which turns our yaml api descriptions into a swagger json file. * tweak serveSpec to add another header when serving the generated json. * add a link to the generated index which will (via js hackery) redirect to our hosted swagger UI at http://matrix.org/docs/api/client-server, with a "url" query-param pointing at the generated json. Also, factor makeTempDir out of gitClone, so that we can give clearer log lines. |
8 years ago | |
|---|---|---|
| .. | ||
| continuserv | ||
| contrib | ||
| css | ||
| speculator | 8 years ago | |
| README.md | ||
| add-matrix-org-stylings.pl | ||
| dump-swagger.py | ||
| gendoc.py | ||
| swagger-http-server.py | ||
README.md
Generating the HTML for the specification
Requirements:
- docutils (for converting RST to HTML)
- Jinja2 (for templating)
- PyYAML (for reading YAML files)
Nix[2] users can enter an environment with the appropriate tools and
dependencies available by invoking nix-shell contrib/shell.nix in this
directory.
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