Статьи

Использование 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.

Библиотека swagger-node поставляется с хорошим редактором для определения API и интегрированным веб-приложением для тестирования API. Следуя первому процессу разработки API, вы можете использовать фиктивный режим для «тестирования» API без фактической реализации API / контроллеров. С помощью команды проверки вы можете проверить правильность определений API и структур проекта. Существует мастер для создания проектов для различных структур API, таких как Express, Connect и другие, которые создают базовую структуру и конфигурацию для новых проектов.

Существует простая инструкция из пяти шагов, чтобы создать свой первый пример hello world. Я не буду повторять шаги здесь. Только одна вещь, которая смутила меня. Пример определяет, что он возвращает JSON, но на самом деле он возвращает только тип контента JSON со строкой. Поэтому я изменил одну строку в файле controllers / hello_world.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});
}

Чтобы запустить проект Swagger, вам нужно вызвать команду «swagger project start» или «node app.js», если вы хотите запустить только основное приложение Node. После этого вы можете запустить API и получить определение API Swagger.

http://127.0.0.1:10010/hello?name=Scott
http://127.0.0.1:10010/swagger

Чтобы запустить редактор, вызовите команду «swagger project edit».

http://127.0.0.1:51351/#/
http://127.0.0.1:51351/editor/spec

Вот скриншот редактора с примером Hello World.