Metadata-Version: 2.0
Name: fairy-slipper
Version: 0.1.0
Summary: A project to make OpenStack API's self documententing.
Home-page: http://www.openstack.org/
Author: OpenStack
Author-email: russell.sim@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Environment :: OpenStack
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Requires-Dist: pbr (>=0.6,!=0.7,<2.0)
Requires-Dist: Babel (>=1.3)
Requires-Dist: oslo.serialization
Requires-Dist: webob
Requires-Dist: docutils
Requires-Dist: pecan
Requires-Dist: jinja2
Requires-Dist: prettytable

=============
fairy-slipper
=============

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/



