openstack
/
fairy-slipper
Code Issues Proposed changes
RETIRED, API documentation generator and builder for OpenStack
178 Commits 1 Branch 2 Tags 1.5 MiB
Go to file
Jenkins ba4fd1e238 Merge "Handle other status codes" 2016-02-22 16:44:48 +00:00
doc/source Fills out outline for how-to and concept articles in API Guides 2015-12-02 10:40:27 -06:00
fairy_slipper Merge "Handle other status codes" 2016-02-22 16:44:48 +00:00
public Fix for issue #43, processing of 2015-12-02 16:06:37 -05:00
releasenotes Adds initial release notes entry to release 0.1.0 2016-01-21 19:18:09 +01:00
tools Fix venv path 2016-02-15 16:58:55 +09:00
.bowerrc Implemented Initial Prototype 2015-07-24 08:29:52 +10:00
.coveragerc Removed unrecognised section from coveragerc 2015-09-27 09:50:47 +10:00
.gitignore Adds releasenotes using the reno tool 2016-01-19 21:11:35 +01:00
.gitreview Fix gitreview file 2016-01-11 18:26:42 +00:00
.mailmap Implemented Initial Prototype 2015-07-24 08:29:52 +10:00
.testr.conf Implemented Initial Prototype 2015-07-24 08:29:52 +10:00
.travis.yml Moved back with explicit path for executable 2015-09-10 08:43:45 +10:00
CONTRIBUTING.rst Update the launchpad bug link in CONTRIBUTING.rst 2016-01-25 13:27:44 +05:30
Gruntfile.js Implemented Initial Prototype 2015-07-24 08:29:52 +10:00
HACKING.rst Implemented Initial Prototype 2015-07-24 08:29:52 +10:00
LICENSE Implemented Initial Prototype 2015-07-24 08:29:52 +10:00
MANIFEST.in Implemented Initial Prototype 2015-07-24 08:29:52 +10:00
README.rst Updates README file now that tool is in OpenStack org 2016-01-19 10:07:42 -06:00
babel.cfg Implemented Initial Prototype 2015-07-24 08:29:52 +10:00
bower.json Removed dependency on angular-swagger-ui 2015-09-20 14:50:15 +10:00
config.py PEP8 Fixes 2015-09-02 18:20:59 +10:00
fairy_slipper.wsgi Implemented Initial Prototype 2015-07-24 08:29:52 +10:00
karma.conf.js Increase the karma timeout 2015-09-27 12:41:03 +10:00
migrate.sh Merge "Handle other status codes" 2016-02-22 16:44:48 +00:00
openstack-common.conf Implemented Initial Prototype 2015-07-24 08:29:52 +10:00
package.json More updates for generating valid swagger 2016-01-19 06:29:01 -05:00
requirements.txt Updates requirements.txt for PBR error and adds xsd:base64binary 2015-08-17 21:57:12 -05:00
run_server.sh Add bower to run_server.sh script 2015-08-20 21:46:40 +10:00
run_tests.sh Added run_tests.sh script 2015-09-10 09:05:26 +10:00
setup.cfg Updates for generating valid swagger. 2016-01-06 16:48:18 -05:00
setup.py Implemented Initial Prototype 2015-07-24 08:29:52 +10:00
test-requirements.txt Adds releasenotes using the reno tool 2016-01-19 21:11:35 +01:00
tox.ini Adds releasenotes using the reno tool 2016-01-19 21:11:35 +01:00

README.rst

fairy-slipper

A project to make OpenStack API's self documententing.

Features

  • Migrates WADL source to Swagger files
  • Provides display of RST plus Swagger JSON files in a web browser

Development

First run the migrate script to initially migrate the content from wadl:

./migrate.sh

This script will checkout the current version of the documentation.

To run the webserver use:

./run_server.sh

A Pecan based webserver will then listen on http://127.0.0.1:8080

AngularJS

To develop the AngularJS component, it's easiest if you use the grunt webserver:

grunt

You will still need to run the Fairy-Slipper webserver, but this will enable auto reloading if you visit the port http://127.0.0.1:9000

Directory Structure (Future)

Current documentation output layout:

api-doc/ -- the root of the documentation
api-doc/index.json  -- the index file that lists all the files that are included in the API doc.
api-doc/<service>/<version>.rst
api-doc/<service>/<version>/<request_schema>.json
api-doc/<service>/<version>/<response_schema>_<status_code>.json
api-doc/<service>/<version>/examples/<request>_req.json
api-doc/<service>/<version>/examples/<response>_resp_<status_code>.json
conversion_files_valid/<service-version>.json -- valid Swagger files

Other Swagger UIs

Taken from https://github.com/swagger-api/swagger-spec/wiki/Sites-and-Services

Other API documentation Tools

Alternative Clients

Other Useful Tools