insomnia documenter

Как Postman Documenter, но для Insomnia! С помощью этого инструмента вы можете создавать красивые страницы документации API, используя файл экспорта Insomnia.

Демо: https://insodoc.github.io/insomnia-documenter/
Учебное и демонстрационное видео: https://www.youtube.com/watch?v=pq2u3FqVVy8.

Оглавление

• Оглавление
• Требования
• Начиная
  • Использование npx
  • Установив пакет глобально
  • Параметры
  • Использование выпуска GitHub
• Обновление API
• Пользовательские корневые пути
• Запуск страницы локально
• Плагин бессонницы
• Журнал изменений
• Вклад
• Лицензия
• Документатор бессонницы для предприятий

Требования

• Node.js (рекомендуется 8.x или выше)
• Экспортированное рабочее пространство Insomnia в формате JSON (v4).

Начиная

Insomnia Documenter предлагает инструмент CLI, упрощающий настройку страницы документации. Вы можете использовать его двумя способами.

Использование npx

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

Установив пакет глобально

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

Параметры

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

Использование выпуска GitHub

Альтернативно вы можете начать использовать Insomnia Documenter, загрузив архив выпуска с GitHub и добавив файл экспорта insomnia.json в корневой каталог вашего сайта.

Обновление API

Обновить API очень просто! Поскольку Insomnia Documenter представляет собой веб-приложение с функцией Plug-and-Play, вы можете просто заменить файл insomnia.json новым экспортированным файлом JSON. Просто убедитесь, что он называется insomnia.json .

То же самое относится и к логотипу ( logo.png ) и значку ( favicon.ico ).

Пользовательские корневые пути

Может быть, вы хотите задокументировать несколько API в одном домене? Возможно, вы хотите разместить свою страницу документации на страницах GitHub? В этом (во многих других случаях) вам нужно будет указать корневой путь. Для этого вам необходимо открыть index.html и заменить следующую строку:

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

с чем-то вроде этого:

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

В этом случае приложение получит файл insomnia.json из каталога /path/to/docs . Это дает вам больше гибкости в выборе способа ведения страницы документации (например, вы можете хранить файл экспорта где-нибудь, кроме корневого каталога веб-страницы). НЕ следует помещать косую черту в конце свойства data-root .

Обратите внимание, что установка этого атрибута не повлияет на значок и логотип страницы. Они по-прежнему будут загружаться из того же каталога, где находится index.html .

Запуск страницы локально

Открытие файла index.html не загрузится в 99,9% случаев, потому что именно так работает выборка. Чтобы просмотреть страницу локально, вы можете использовать такой инструмент, как zeit/serve:

npx serve

Страница будет доступна по адресу http://localhost:5000.

Плагин бессонницы

devhammed создал потрясающий плагин Insomnia, который позволяет создавать страницу документации непосредственно из интерфейса Insomnia. Получить плагин (npm — github)

Журнал изменений

Пожалуйста, ознакомьтесь с документом журнала изменений.

Вклад

Инструмент CLI представляет собой командный апплет, а сам интерфейс представляет собой приложение Svelte. Этот проект все еще находится в стадии бета-тестирования, а это значит, что в нем есть ошибки и его можно кое-где улучшить. Вклад приветствуется :)

Клонируем репозиторий:

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

Установите зависимости:

npm install

Скопируйте демонстрационный файл экспорта Insomnia:

cp docs/insomnia.json public/insomnia.json

Запустите сборку для разработки с горячей перезагрузкой:

npm run dev

Создайте производственную сборку:

npm run build

Линтинг:

npm run lint

Тестирование:

npm run test 

Лицензия

Массачусетский технологический институт.

Примечание: этот проект не связан с Kong и/или Insomnia.

Документатор бессонницы для предприятий

Доступно как часть подписки Tidelift.

Разработчики Insomnia Documenter и тысяч других пакетов сотрудничают с Tidelift, предоставляя коммерческую поддержку и обслуживание зависимостей с открытым исходным кодом, которые вы используете для создания своих приложений. Экономьте время, снижайте риски и улучшайте работоспособность кода, платя при этом специалистам по сопровождению именно тех зависимостей, которые вы используете. Узнать больше.