fairy-slipper 0.2.0

A project to make OpenStack API's self documententing.

A project to make OpenStack API’s self documententing.

• Free software: Apache license

• Documentation: doc/source directory

• Source: https://git.openstack.org/cgit/openstack/fairy-slipper

• Bugs: https://bugs.launchpad.net/openstack-doc-tools

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

• http://docs.apimatic.apiary.io/

• http://docs.api2cart.com/post/interactive-docs

• http://chat.banckle.com/api/v3.0/

• http://www.evercam.io/develop/docs

• https://api.elastic.io/docs/

• https://developer.concur.com/

• https://www.callfire.com/api-documentation/rest/version/1.1

• https://www.bitmex.com/api/explorer/

• https://bitdango.com/api

• https://api.groupdocs.com/v2.0/spec/

• http://developer.wordnik.com/docs.html

• https://api.sensr.net/doc/v3/index.html

Other API documentation Tools

• https://github.com/danielgtaylor/aglio

Alternative Clients

• https://github.com/Orange-OpenSource/angular-swagger-ui

• https://github.com/apigee-127/swagger-client-API

• https://github.com/signalfx/swagger-ajax-client/

• https://github.com/signalfx/swagger-angular-client

• https://github.com/signalfx/swagger-client-generator

Other Useful Tools

• http://jsonschema.net/