Skip to content

Latest commit

 

History

History
169 lines (113 loc) · 5.65 KB

README.md

File metadata and controls

169 lines (113 loc) · 5.65 KB
Raw

API Doxygen

API Doxygen is a customised version of Documentor — it is intended to be used in with API Designer and API Swagger. Akin to Postman's Documenter but for API-Designer (i.e. Insomnia), it is based on Svelte — the « cybernetically enhanced » application framework, to automagically generate your API documentation :smile:.

Objectives ---

All credits for this software goes to its original authors. Customisations here intend to:

  • Transform into a GitHub template
  • Automate the build through a Makefile and GitHub Actions
  • Reduce the (numerous) dependencies
  • And probably migrate to SveleKit

Important: We focus on macOS and Linux — stick with Documentor if you are on Windows.

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

Install configuration file

npx 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 API path

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 git@github.com:jozsefsallai/insomnia-documenter.git
cd insomnia-documenter

Install the dependencies:

npm install

Copy the demo Insomnia export file:

cp demo/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.