The goal of Spectacle is help you “save time and look good” by using a well written spec to automatically generate your API docs. Using an API spec to generate your docs has a number of great advantages:
- Maintain a single source: Save time by removing the need to maintain a separate API spec and API documentation.
- No more out-of-date documentation: Your documentation will always be up-to-date with your API spec.
- Be a better developer: Your entire API system will be more stable and robust when built around your spec as a single source of truth.
- Documentation is just the beginning: Generate your API system from your spec, including; tests, client implementations, and server code. See also Optimizing Your Workflow
See a demo of Spectacle in action here: http://cheesestore.github.io
- OpenAPI/Swagger 2.0 support: Support for the latest OpenAPI/Swagger specification - the new standard for documenting REST APIs.
- Clean responsive design: Spectacle features a responsive HTML5 and CSS3 layout built with Foundation 6 that looks great on all devices and screen sizes.
- Embed into your existing website: Spectacle features an embedded option that lets you generate docs without a HTML
<body>layout for convenient integration into your existing website.
- Live preview developer mode: Spectacle comes with a development mode that starts a local HTTP server with a file watcher and live reload so you can preview changes to your live documentation in your browser as you write your spec.
- Configurable templates and styles: Spectacle is built with easily configurable Handlebars templates and SCSS styles so you can add your own flavor. See Custom Builds
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 your_swagger_api.json # Or use the cheese.json example to test it out # spectacle test/fixtures/cheese.json
Your generated documentation will be located in the
/public directory. You can either copy the generated HTML to your web server, or view your docs by starting the internal web server like so:
Now point your browser to http://localhost:4400/ and presto - sexy docs for your API!
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.
appto 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
Optimizing Your Workflow
If you’re a developer you are always looking for ways to optimize your workflow. The great thing about the Swagger spec is that it enables you to use your API spec as a source for automating and generating all parts of your API system, such as:
- Inline Code Generators: Generate your Swagger JSON or YAML from your source code comments.
- Automate Testing: Automate testing for all your API endpoints.
- Code Generation: Automatically generate client and server code from your spec.
- Generate Documentation: Really?
For a list of open source libraries in many languages check here: http://swagger.io/open-source-integrations/
Please use the GitHub issue tracker if you have any ideas or bugs to report.
All contributions are welcome.
Good luck and enjoy Spectacle!