Использование Swagger в приложениях Node.js для API документов

Как я уже писал ранее, мне нравится эта модель для документирования API непосредственно в исходном коде, где реализованы API. Это помогает разработчикам помнить о необходимости синхронизации реализации и документации API-интерфейсов, а также повышает осведомленность о совместимости API-интерфейсов. Вы можете использовать этот подход не только для приложений Java, но и для приложений Node.js, использующих популярную среду веб-приложений Express , например, через модуль npm swagger-node-express . Проверьте метод «findById» в примере.

Однако я не уверен насчет статуса этого модуля. Он ссылается на проект GitHub github.com/swagger-api/swagger-node-express, который, похоже, больше не существует. Вместо этого он перенаправляет на другой библиотечный swagger-узел, который кажется преемником или заменой. Хотя библиотека swagger-node поставляется с множеством дополнительных приятных возможностей, я еще не выяснил, как документировать API непосредственно в исходном коде. Модуль swagger-node использует отдельные файлы yaml для определения API. В этой модели документация по API близка к реализации API, но не напрямую в тех же файлах. Поскольку модуль узла-сваггера связан с сайтом Swagger и поскольку код находится в API-интерфейсе Swagger Организация GitHub, ниже я опишу, как использовать этот модуль в приложениях Node.js.

function hello(req, res) {
  // variables defined in the Swagger document can be referenced using req.swagger.params.{parameter_name}
  var name = req.swagger.params.name.value || 'stranger';
  var hello = util.format('Hello, %s!', name);

  // this sends back a JSON response which is a single string
  //res.json(hello);

  res.json({ message: hello});
}