The gentleman at REST
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
<body>for convenient integration into your existing website.
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.json
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/.
A basic Docker script is included that allows Spectacle to be run from the inside, not outside. It's useful, for instance, in a Gitlab CI pipeline. Thanks @alexeiaguiar.
How to use it:
docker run -it sourcey/spectacle /bin/sh
The basic CLI options are detailed below:
Most options are self explanatory, but the following options warrant some further explanation:
-d: This option starts a development server with a file watcher and live reload, and will automatically regenerate your docs when any of your spec or app files change.
-s: This option starts a production server without any development options enabled that serves the contents of your
-e: This option lets you build a minimal version of the documentation without the HTML
<body> tags, so you can embed Spectacle into your own website template. More info on custom builds here.
app to a remote location or a separate repo for custom builds.
-t: This option specifies where the generated documentation HTML files will be output.
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 email@example.com:<yourname>/spectacle.git to make your own changes.
Alternatively, you can just copy the contents of
app path to the CLI like so:
spectacle -a /path/to/your/app your_swagger_api.json
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/
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.
npm test on the repository to start the automated tests.
Some parts of testing can be configured using environment variables.
OFFLINE=trueSome tests use HTTP connections to test giving Spectacle remote API specifications. Use
OFFLINE=trueto skip tests that require an internet connection.
Include environment variables before calling
npm test. For example,
OFFLINE mode can be enabled via
OFFLINE=true npm test.
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!