Generate beautiful Swagger API documentation from Insomnia

I recently built a tool called Swaggymnia to generate Swagger documentation for an existing API in Insomnia REST client. So brace yourself for a short but interesting quick tip read.

Start by downloading Swaggymnia, find the appropriate package for your system and download it. For linux:

1
wget https://s3.amazonaws.com/swaggymnia/1.0.0-beta/linux/swaggymnia

After downloading Swaggymnia. Add the execution permission to the binary:

1
chmod +x swaggymnia


Note: For Windows make sure that swaggymnia binary is available on the PATH. This page contains instructions for setting the PATH on Windows.

After installing, verify the installation worked, by opening a new terminal session and checking if swaggymnia is available :



Once done, export your API from Insomnia:



Next, create a configuration file with the format below:

1
2
3
4
5
6
7
8
{
"title" : "API Name",
"version" : "API version",
"host" : "API URL",
"bastPath" : "Base URL",
"schemes" : "HTTP protocol",
"description" : "API description"
}

Then, issue the following command:

1
swaggymnia generate -i watchnow.json -c config.json -o yaml

As result, you should see a new file called swagger.yml generated:



Now our Swagger spec is generated, you can publish your Swagger spec as customer-facing documentation.



For this purpose you can use Swagger UI, which converts your Swagger spec into a beautiful, interactive API documentation.

You can download Swagger UI from here. It is just a bundle of HTML, CSS and JS files, which doesn’t require a framework or anything, so they can be installed in a directory on any HTTP server.

Once you have downloaded it, you put your swagger.yaml file into the dist directory — and open index.html and change it to point at your swagger file instead of http://petstore.swagger.io/v2/swagger.json.

Then you can open index.html in your browser, and see your new beautiful, interactive API documentation:



Make sure to drop your comments, feedback, or suggestions below — or connect with me directly on Twitter @mlabouardy

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×