Home

Awesome

Spectacle

The gentleman at REST

CircleCI

Spectacle generates beautiful static HTML5 documentation from OpenAPI/Swagger 2.0 API specifications.

The goal of Spectacle is help you "save time and look good" by providing an extensible platform for auto generating your REST API docs. The default layout is a three column single page, similar to those employed by Stripe and Intercom.

See a demo of Spectacle in action here: http://cheesestore.github.io


Demo Screenshot


Features

Usage

Simply install Spectacle from npm like so:

npm install -g spectacle-docs

Next pass your swagger.json document use the CLI to generate your documentation.

spectacle -d your_swagger_api.json

# Or use the cheese.json example to test it out
# spectacle -d -l test/fixtures/cheese.png test/fixtures/cheese.yml

Your generated documentation will be located in the public directory by default. You can either copy the generated HTML to your web server, or view your docs by pointing your browser to http://localhost:4400/.

Docker

Docker images are included that allow Spectacle to be run from the inside. It's useful, for instance, in a Gitlab CI pipeline. Thanks @alexeiaguiar.

How to use it: docker run -it sourcey/spectacle /bin/sh

Configuration Options

The basic CLI options are detailed below:

$ spectacle -h

  Usage: spectacle [options] <specfile>

  Options:

    -h, --help                   output usage information
    -V, --version                output the version number
    -C, --disable-css            omit CSS generation (default: false)
    -J, --disable-js             omit JavaScript generation (default: false)
    -e, --embeddable             omit the HTML <body/> and generate the documentation content only (default: false)
    -d, --development-mode       start HTTP server with the file watcher (default: false)
    -D, --development-mode-live  start HTTP server with the file watcher and live reload (default: false)
    -s, --start-server           start the HTTP server without any development features
    -p, --port <port>            the port number for the HTTP server to listen on (default: 4400)
    -P, --port-live <port>       the port number for the live reload to listen on (default: 4401)
    -t, --target-dir <dir>       the target build directory (default: public)
    -f, --target-file <file>     the target build HTML file (default: index.html)
    -a, --app-dir <dir>          the application source directory (default: app)
    -l, --logo-file <file>       specify a custom logo file (default: null)
    -c, --config-file <file>     specify a custom configuration file (default: app/lib/config.js)

Most options are self explanatory, but the following options warrant some further explanation:

Custom Builds

The best option for building your own custom functionality into Spectacle is to fork Spectacle on GitHub, and make your own modifications in source. This way you can keep up to date by merging changes from the master branch, and your can also contribute your updates back to master by creating a Pull Request if you think they improve Spectacle somehow.

To fork Spectacle go to https://github.com/sourcey/spectacle, and press the 'Fork' button. Now you can git clone git@github.com:<yourname>/spectacle.git to make your own changes.

Alternatively, you can just copy the contents of app from the main repo which contains all the source files such as templates, stylesheets and JavaScripts. Now just pass the path to your custom app path to the CLI like so: spectacle -a /path/to/your/app your_swagger_api.json

Optimizing Your Workflow

Using an API spec to generate your docs has a number of great advantages, such as:

As developer we're always looking for ways to improve and optimize our workflow, and documentation is just the beginning. With a well written Swagger you can automate and generate many parts of your API system, such as:

For a list of open source Swagger based libraries in many languages check here: http://swagger.io/open-source-integrations/

Development

Testing

Testing is powered by Mocha/Chai, and automated testing is run via CircleCI.

At this stage, unit tests have not been written for all parts of the codebase. However, new code should be tested, and unit tests for the existing code will be added in the future.

Run npm test on the repository to start the automated tests. Some parts of testing can be configured using environment variables.

Include environment variables before calling npm test. For example, OFFLINE mode can be enabled via OFFLINE=true npm test.

<!-- ## Contributors Thanks to all the great developers who make Spectacle great! TODO -->

More Information

More info is available on the Spectacle homepage.

Please use the GitHub issue tracker if you have any ideas or bugs to report.

All contributions are welcome.

Good luck and enjoy Spectacle!