Как использовать Swagger с Hapi?

У меня есть обычное приложение Hapi, которое я планирую перенести на Swagger. Я установил swagger-node с помощью официальных инструкций и выбрал Hapi при выполнении 'проекта сборки swagger'. Тем не менее, я теперь запутался, потому что, кажется, существует несколько библиотек для интеграции swagger- node и hapi:

  • hapi-swagger: самый популярный
  • hapi-swaggered: несколько популярный
  • swagger-hapi: непопулярный и не активный, но используемый официальной библиотекой Swagger Node.js(т.е. swagger-node) по умолчанию для проектов Hapi

Я, хотя swagger-hapi был "официальным" подходом, пока не попытался найти информацию о том, как различные конфигурации на маршрутах Хапи (например, авторизация, обзор и т.д.). Похоже, что подходы принципиально разные, чарг-хапи принимает определение Swagger в качестве входных данных и автоматически генерирует маршруты, тогда как hapi-swagger и hapi-swaggered, похоже, имеют схожий подход друг с другом, только генерируя документацию Swagger API от простого старого Hapi определения маршрутов.

Учитывая количество участников и количество загрузок, hapi-swagger, похоже, подходит, но я не уверен, как действовать дальше. Существует ли "официальный" способ Swagger для настройки Hapi, и если есть, как настроить аутентификацию (желательно с помощью hapi-auth-jwt2, или другое подобное JWT-решение) и авторизацию?

EDIT: я также нашел swaggerize-hapi, который, как утверждается, поддерживается командой kraken.js с открытым исходным кодом PayPal, которая указывает, что она может имеют какую-то корпоративную поддержку (всегда хорошая вещь). swaggerize-hapi, похоже, очень похож на hapi-swagger, хотя последний, похоже, предоставляет больше функциональных возможностей (главным образом редактор Swagger).

Ответ 1

Изменить: пункт 3. из вашего вопроса и понимание того, что swagger-hapi действительно очень важно. Он не напрямую обслуживает swagger-ui html. Он не предназначен, но он позволяет реализовать всю идею взлома (что другие проекты в точках 1 и 2. на самом деле немного реверсируют). См. Ниже.

Оказывается, когда вы используете swagger-node и swagger-hapi вам не нужны все остальные упомянутые вами пакеты, за исключением использования swagger-ui напрямую (что используется всеми остальными в любом случае - они обертывают его в зависимости)

Я хочу поделиться своим пониманием до сих пор в этой головоломке hapi/swagger, надеюсь, что эти 8 часов, которые я потратил, могут помочь и другим.

Библиотеки, такие как hapi-swaggered, hapi-swaggered-ui, также hapi-swagger - все они следуют одному и тому же подходу - это может быть описано так:

You document your API while you are defining your routes

Они несколько сидят в стороне от основной идеи swagger-node и проекта hello_world, созданного с помощью swagger-cli, о котором вы говорили, что используете.

Пока swagger-node и swagger-hapi (Обратите внимание, что его отличие от hapi-swagger):

You define all your API documentation and routes **in a single centralized place - swagger.yaml**

а затем просто сосредоточьтесь на написании логики контроллера. Проект шаблонов, снабженный swagger-cli, уже разоблачает это централизованное место swagger.yaml как json через конечную точку /swagger.

Теперь, поскольку проект swagger-ui, который все вышеперечисленные пакеты используют для показа пользовательского интерфейса, представляет собой всего лишь кучу static html - для его использования у вас есть два варианта:

  • 1) для самостоятельного размещения этого статического html из вашего приложения

  • 2) разместить его в отдельном веб-приложении или даже загрузить index.html непосредственно из файловой системы.

В обоих случаях вам просто нужно прокормить swagger-ui с помощью swagger json, который, как сказано выше, уже отображается конечной точкой /swagger.

Единственное предостережение, если вы выбрали вариант 2), заключается в том, что вам нужно включить cors для этой конечной точки, что оказалось очень простым. Просто измените свой default.yaml, чтобы также использовать волынку cors. См. Этот поток для того, как это сделать.

Как сказал @Kitanotori выше, я также не вижу смысла программно документировать код. Идея просто описать все в одном месте и заставить как код, так и механизм документации понять это, замечательна.