swaggerНачало работы с swagger


замечания

В этом разделе представлен обзор того, что такое swagger, и почему разработчик может захотеть его использовать.

Он также должен упомянуть о любых крупных предметах в чванстве и ссылки на связанные темы. Поскольку документация для swagger является новой, вам может потребоваться создать начальные версии этих связанных тем.

Введение - Установка - Настройка (разработка в Node.js)

Вступление:

Swagger - это набор правил / спецификаций для формата, описывающего API REST. Он обеспечивает мощную и активно развитую экосистему инструментов вокруг этой формальной спецификации, такой как генераторы кода и редакторы. Лучшая часть Swagger заключается в том, что документация методов, параметров и моделей тесно интегрирована в код сервера, позволяя API всегда оставаться в синхронизации. Вот ссылка, дающая краткий обзор того, что такое чванство: начало работы.

Технические характеристики написания:

Спецификации могут быть записаны в JSON или YAML. И поэтому мы делаем файл swagger.json или swagger.yaml соответствующим образом. Для создания файла можно использовать онлайн-редактор. Вот ссылка, описывающая синтаксис спецификаций: http://swagger.io/specification/

Способы использования swagger:

  1. API-первый подход (подход сверху вниз): используйте редактор swagger → Определите определения чванства → Используйте swagger-codegen и swagger-ui для создания API-интерфейсов
  2. Первый подход к сервису (подход Bottom up): Разработайте классы ресурсов JAX-RS с использованием аннотаций swagger → Используйте buagger-core, чтобы автоматически генерировать определения swagger → Использование swagger-codegen и swagger-ui для создания клиентских API и документации. Вышеприведенное может быть сделано во время сборки maven во время плагина mawag.

Установка и настройка

В этом разделе мы установим swagger, настроим пользовательский интерфейс swagger и сгенерируем его на стороне сервера и клиента SDK. Для установки swagger с помощью диспетчера пакетов Node выполните следующую команду:

npm install -g swagger

Использование флага '-g' гарантирует, что модуль будет установлен глобально. Затем мы создадим проект, используя следующую команду:

swagger project create <project-name>

Это попросит пользователя выбрать структуру для разработки API REST. Express можно выбрать для одного и того же. Это создаст каталог проекта со следующими элементами и файлом README.md в каждом из них:

  • апи /
    • контроллеры /
    • хелперы /
    • издевается /
    • чванство /
  • конфиг /
  • тестовое задание/
    • апи /
      • контроллеры /
      • помощники
  • app.js
  • package.json

Сервер в настоящее время готов к работе и может быть запущен с использованием этой команды для выполнения в корне проекта:

swagger project start

Если хост-сервер установлен как localhost а номер порта не изменен в файле app.js , то сервер запускается по адресу: http://localhost:10010 Теперь пользовательский интерфейс swagger может использоваться для дальнейшего развития наших API REST. Это можно запустить в новом терминале, используя:

swagger project edit

Это откроет редактор swagger на вкладке браузера на случайно сгенерированном порту. Образец приветствия GET можно увидеть уже в файле swagger.yaml. Любое дальнейшее изменение этого файла приведет к перезагрузке сервера самостоятельно.

В разделе путей значение, используемое для x-swagger-router-controller должно быть именем файла javascript в папке контроллеров. В качестве примера, hello_world.js должен присутствовать в каталоге контроллеров. Кроме того, значение параметра operationId представляет собой имя функции в приведенном выше файле javascript. Здесь должна быть написана бизнес-логика. Таким образом, наша настройка swagger завершена и может быть использована для дальнейшего развития нашего API.