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