If you never heard of Spectacle it’s a platform developed by Sourcey with the goal to generate beautiful documentation from OpenAPI/Swagger 2.0 API specifications.
Using Spectacle is very straight forward but before doing so you must go through some steps.
- Install Node.js
First things first. To use Spectacle, you need npm and to have npm you have to install Node.js.
If you’re on Windows just follow this link, download and run the .msi file.
- Install Spectacle
Now that you have Node.js to install Spectacle just open cmd and install it from npm like so:
npm install -g spectacle-docs
- Configure Swagger
If you’re already using Swagger in your project then you could generate the documentation via Spectacle right away, but before doing so we’re going to do some tweaks on the Swagger UI configuration to make our lives easier.
To generate the documentation, Spectacle needs a swagger.json which you can get from Swagger UI. By default, when accessing Swagger UI, you’ll be presented to something of the likes of this:
If you open with your browser the Url shown in the Swagger UI search bar, you’ll be redirected to the json document.
Now, this is a perfectly acceptable way to access the json but to me it’s a bit cumbersome.
My suggestion would be to edit the Swagger Configuration of your project such to show a direct link to the json file. You can do so by editing SwaggerDocsConfig’s Description property.
Now your Swagger UI will have a very handy link to the swagger.json document.
- Generate the documentation
To generate the documentation download the swagger.json, open cmd and run the following command:
Spectacle -d swagger.json
The documentation will be in the public directory by default. You can open the generated HTML with your browser, or view your docs by pointing your browser to http://localhost:4400/.
And that’s it.
If you want to know how you can embellish your response documentation with Swashbuckle, be free to take a look at this example.
