Находясь в бэкэнд-разработке, очень важно правильно задокументировать ваш API, чтобы его могли понять люди, которые будут использовать ваш API.

Правильная документация также важна, как и создание самого API, но ни один разработчик не считает создание документа очень интересным, потому что это очень скучно.

Некоторые предлагают использовать «Swagger» для создания документации для API, но опять же для этого вам нужно изучить Swagger, а кто действительно хочет чему-то научиться, просто чтобы создать документацию для API

Есть один простой способ создать документ с помощью POSTMAN и DOCGEN.

Если вам просто нужна документация от почтальона, просто щелкните правой кнопкой мыши коллекцию в почтальоне и нажмите «опубликовать документ», вам будет предложено некоторая базовая информация, такая как среда для выбора и т. Д., А затем почтальон сгенерирует документ для вашего API от имени вы, ссылка будет сгенерирована, где вы сможете увидеть всю вашу документацию по API, НО

Допустим, вы хотите иметь надлежащую документацию, чтобы показать пользователю, когда пользователь посещает базовый маршрут API, например: localhost: 3000, а затем как легко сгенерировать файл index.html и поместить этот файл index.html в общей папке и отправить его в качестве ответа по тому же базовому маршруту.

Действия, которые необходимо выполнить, если вы являетесь пользователем Mac: (Примечание. Homebrew должен быть установлен раньше)

  • варить обновление
  • экспортируйте свою коллекцию почтальонов, в которой есть все ваши API
  • скажем, имя экспортированной коллекции - postmanexported.json
  • Установите docgen на Mac, см. Ниже 2 команды
brew tap thedevsaddam/cli https://github.com/thedevsaddam/homebrew-cli.git
brew install docgen

Создание файла index.html с помощью docgen

docgen build -i ~/Desktop/postmanexported.json -o ~/Desktop/index.html

Я предполагаю, что ваш экспортированный JSON присутствует на рабочем столе, файл index.html будет создан на рабочем столе

Скопируйте этот файл index.html и вставьте его в общую папку вашего API или по пути, который вызывается из базового маршрута = ›localhost: 3000 /

Теперь, когда вы откроете localhost: 3000, вы найдете надлежащую документацию по вашему API.

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

У него нет вызова API напрямую из документа, как у swagger.

Удачного обучения!