yunshuaipeng / insomnia-documenter

Tool to create minimalist and beautiful API documentation pages using your Insomnia workspace export file.

Like Postman Documenter but for Insomnia! With this tool you can generate beautiful API documentation pages using your Insomnia export file.

Demo: https://jozsefsallai.github.io/insomnia-documenter
Tutorial and demo video: https://www.youtube.com/watch?v=pq2u3FqVVy8

Table of Contents

• Requirements
• Getting Started
  • Using npx
  • By installing the package globally
  • Options
  • Using a GitHub Release
• Updating the API
• Custom Root Paths
• Running the Page Locally
• Insomnia Plugin
• Changelog
• Contribution
• License
• Insomnia Documenter for enterprise

Requirements

• Node.js (8.x or higher is recommended)
• An exported Insomnia workspace JSON (v4)

Getting Started

Insomnia Documenter offers a CLI tool to make it super easy to set up a documentation page. You can use it in two ways.

Using npx

npx insomnia-documenter --config /path/to/insomnia/config.json

By installing the package globally

npm i -g insomnia-documenter
insomnia-documenter --config /path/to/insomnia/config.json

Options

Options:
  -c, --config <location>  Location of the exported Insomnia JSON config.
  -l, --logo <location>    Project logo location (48x48px PNG).
  -o, --output <location>  Where to save the file (defaults to current working directory).
  -h, --help               output usage information

Using a GitHub release

Alternatively, you can start using Insomnia Documenter by downloading a release archive from GitHub and adding your insomnia.json export file to the root directory of your site.

Updating the API

Updating the API is super simple! Since Insomnia Documenter is a plug-and-play web app, you can just replace your insomnia.json with your new exported JSON file. Just make sure it's called insomnia.json.

The same actually applies to the logo as well (logo.png).

Custom Root Paths

Maybe you want to document multiple APIs on the same domain? Perhaps you want to host your documentation page on GitHub pages? In this (any many other cases), you will need to specify what the root path is. To do this, you have to open index.html and replace the following line:

<div id="app"></div>

with something like this:

<div id="app" data-root="/path/to/docs"></div>

In this case, the app will pick up the insomnia.json file from the /path/to/docs directory. This gives you more flexibility over how you want to maintain your documentation page (for example, you can store the export file somewhere other than the root directory of the webpage). You should NOT put a trailing slash in the data-root property.

Please note that setting this attribute will not affect the favicon and the logo of the page. They will still be loaded from the same directory where index.html is.

Running the Page Locally

Opening the index.html file will fail to load in 99.9% of cases because that's just how fetch works. To preview the page locally, you might want to use a tool such as zeit/serve:

npx serve

The page will be available at http://localhost:5000.

Insomnia Plugin

devhammed has made an awesome Insomnia Plugin that allows you to generate a documentation page directly from Insomnia's interface. Get The Plugin (npm - github)

Changelog

Please see the Changelog document.

Contribution

The CLI tool is a commander applet, while the frontend itself is a Svelte app. This project is still in beta, which means it has bugs and can be improved here and there. Contribution is most welcome :)

Clone the repository:

git clone [email protected]:jozsefsallai/insomnia-documenter.git
cd insomnia-documenter

Install the dependencies:

npm install

Copy the demo Insomnia export file:

cp docs/insomnia.json public/insomnia.json

Run a development build with hot reload:

npm run dev

Create a production build:

npm run build

Linting:

npm run lint

Testing:

npm run test

License

MIT.

Note: this project is not affiliated with Kong and/or Insomnia.

Insomnia Documenter for enterprise

Available as part of the Tidelift Subscription

The maintainers of Insomnia Documenter and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.