API documentation generator tool for Insomnia.
npm install insomnia-documenterLike 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
Insomnia Documenter offers a CLI tool to make it super easy to set up a documentation page. You can use it in two ways.
``sh`
npx insomnia-documenter --config /path/to/insomnia/config.json
`sh`
npm i -g insomnia-documenter
insomnia-documenter --config /path/to/insomnia/config.json
`
Options:
-c, --config
-l, --logo
-f, --favicon
-o, --output
-h, --help output usage information
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 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 (logo.png) e favicon (favicon.ico) as well .
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:
`html`
with something like this:
`html`
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.
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:
`sh`
npx serve
The page will be available at http://localhost:5000.
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)
Please see the Changelog document.
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:
`sh`
git clone git@github.com:jozsefsallai/insomnia-documenter.git
cd insomnia-documenter
Install the dependencies:
`sh`
npm install
Copy the demo Insomnia export file:
`sh`
cp docs/insomnia.json public/insomnia.json
Run a development build with hot reload:
`sh`
npm run dev
Create a production build:
`sh`
npm run build
Linting:
`sh`
npm run lint
Testing:
`sh``
npm run test
MIT.
Note: this project is not affiliated with Kong and/or Insomnia.
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.