Beautiful static documentation generator for OpenAPI/Swagger 2.0

Overview

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

  • OpenAPI/Swagger 2.0 support: Support for the latest OpenAPI/Swagger specification.
  • Highly configurable: Easily configurable Handlebars templates and SCSS styles so you can add your own design and flavour without going bald. See Custom Builds
  • Markdown support: Render markdown written in any of your API descriptions.
  • Remote file references: Support for swagger specs split across multiple files.
  • Clean responsive design: Responsive HTML5 and CSS3 layout built with Foundation 6 that looks great on all devices and screen sizes.
  • Embed into your existing website: An embedded option so that generate partial docs without a HTML for convenient integration into your existing website.
  • Live preview developer mode: Development mode that starts a local HTTP server with a file watcher and live reload so you can preview live changes in your browser as you update your spec.

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:

  • --development-mode -d: This option starts a development server with a file watcher, and will automatically regenerate your docs when any of your spec or app files change.

  • --development-mode-live -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 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.

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 [email protected]: /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:

  • 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.

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:

  • 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 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.

  • OFFLINE=true Some tests use HTTP connections to test giving Spectacle remote API specifications. Use OFFLINE=true to 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 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!

Sphinx-performance - CLI tool to measure the build time of different, free configurable Sphinx-Projects

CLI tool to measure the build time of different, free configurable Sphinx-Projec

useblocks 11 Nov 25, 2022
python package sphinx template

python-package-sphinx-template python-package-sphinx-template

Soumil Nitin Shah 2 Dec 26, 2022
Seamlessly integrate pydantic models in your Sphinx documentation.

Seamlessly integrate pydantic models in your Sphinx documentation.

Franz Wöllert 71 Dec 26, 2022
API Documentation for Python Projects

API Documentation for Python Projects. Example pdoc -o ./html pdoc generates this website: pdoc.dev/docs. Installation pip install pdoc pdoc is compat

mitmproxy 1.4k Jan 07, 2023
NoVmpy - NoVmpy with python

git clone -b dev-1 https://github.com/wallds/VTIL-Python.git cd VTIL-Python py s

263 Dec 23, 2022
Convert excel xlsx file's table to csv file, A GUI application on top of python/pyqt and other opensource softwares.

Convert excel xlsx file's table to csv file, A GUI application on top of python/pyqt and other opensource softwares.

David A 0 Jan 20, 2022
Always know what to expect from your data.

Great Expectations Always know what to expect from your data. Introduction Great Expectations helps data teams eliminate pipeline debt, through data t

Great Expectations 7.8k Jan 05, 2023
Plover jyutping - Plover plugin for Jyutping input

Plover plugin for Jyutping Installation Navigate to the repo directory: cd plove

Samuel Lo 1 Mar 17, 2022
A Python Package To Generate Strong Passwords For You in Your Projects.

shPassGenerator Version 1.0.6 Ready To Use Developed by Shervin Badanara (shervinbdndev) on Github Language and technologies used in This Project Work

Shervin 11 Dec 19, 2022
A simple USI Shogi Engine written in python using python-shogi.

Revengeshogi My attempt at creating a USI Shogi Engine in python using python-shogi. Current State of Engine Currently only generating random moves us

1 Jan 06, 2022
Quickly download, clean up, and install public datasets into a database management system

Finding data is one thing. Getting it ready for analysis is another. Acquiring, cleaning, standardizing and importing publicly available data is time

Weecology 274 Jan 04, 2023
AiiDA plugin for the HyperQueue metascheduler.

aiida-hyperqueue WARNING: This plugin is still in heavy development. Expect bugs to pop up and the API to change. AiiDA plugin for the HyperQueue meta

AiiDA team 3 Jun 19, 2022
My solutions to the Advent of Code 2021 problems in Go and Python 🎄

🎄 Advent of Code 2021 🎄 Summary Advent of Code is an annual Advent calendar of programming puzzles. This year I am doing it in Go and Python. Runnin

Orfeas Antoniou 16 Jun 16, 2022
Automated generation of real Swagger/OpenAPI 2.0 schemas from Django REST Framework code.

drf-yasg - Yet another Swagger generator Generate real Swagger/OpenAPI 2.0 specifications from a Django Rest Framework API. Compatible with Django Res

Cristi Vîjdea 3k Dec 31, 2022
DeltaPy - Tabular Data Augmentation (by @firmai)

DeltaPy⁠⁠ — Tabular Data Augmentation & Feature Engineering Finance Quant Machine Learning ML-Quant.com - Automated Research Repository Introduction T

Derek Snow 470 Dec 28, 2022
DocumentPy is a Python application that runs in a command-line interface environment, made for creating HTML documents.

DocumentPy DocumentPy is a Python application that runs in a command-line interface environment, made for creating HTML documents. Usage DocumentPy, a

Lotus 0 Jul 15, 2021
MkDocs Plugin allowing your visitors to *File > Print > Save as PDF* the entire site.

mkdocs-print-site-plugin MkDocs plugin that adds a page to your site combining all pages, allowing your site visitors to File Print Save as PDF th

Tim Vink 67 Jan 04, 2023
LotteryBuyPredictionWebApp - Lottery Purchase Prediction Model

Lottery Purchase Prediction Model Objective and Goal Predict the lottery type th

Wanxuan Zhang 2 Feb 14, 2022
🏆 A ranked list of awesome python developer tools and libraries. Updated weekly.

Best-of Python Developer Tools 🏆 A ranked list of awesome python developer tools and libraries. Updated weekly. This curated list contains 250 awesom

Machine Learning Tooling 646 Jan 07, 2023
Fastest Git client for Emacs.

EAF Git Client EAF Git is git client application for the Emacs Application Framework. The advantages of EAF Git are: Large log browse: support 1 milli

Emacs Application Framework 31 Dec 02, 2022