spectacle-docs
Advanced tools
Generate beautiful static API documentation from OpenAPI/Swagger 2.0 specifications
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 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:
See a demo of Spectacle in action here: http://cheesestore.github.io
<body> layout 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 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:
spectacle -s
Now point your browser to http://localhost:4400/ and presto - sexy docs for your API!
The basic CLI options are detailed below:
$ spectacle -h
Usage: cli spactacle [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 and live reload (default: false)
-s, --start-server start the HTTP server without any development features
-p, --port <dir> the port number for the HTTP server to listen on (default: 4400)
-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)
-i, --cache-dir <dir> the intermediate build cache directory (default: ./.cache)
-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:
--development-mode -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.
--start-server -s: This option starts a production server without any development options enabled that serves the contents of your --target-dir.
--embeddable -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-dir -a: This option overrides the default directory which contains all the Handlebars templates, SCSS, and JavaScript source files. This option is useful for development because you can copy the contents of app to a remote location or a separate repo for custom builds.
--target-dir -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 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
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:
For a list of open source libraries in many languages check here: http://swagger.io/open-source-integrations/
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!
FAQs
Generate beautiful static API documentation from OpenAPI/Swagger 2.0 specifications
The npm package spectacle-docs receives a total of 161 weekly downloads. As such, spectacle-docs popularity was classified as not popular.
We found that spectacle-docs demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Fluent Assertions is facing backlash after dropping the Apache license for a commercial model, leaving users blindsided and questioning contributor rights.
Research
Security News
Socket researchers uncover the risks of a malicious Python package targeting Discord developers.
Security News
The UK is proposing a bold ban on ransomware payments by public entities to disrupt cybercrime, protect critical services, and lead global cybersecurity efforts.