swagger учебник
Начало работы с swagger
Поиск…
замечания
В этом разделе представлен обзор того, что такое swagger, и почему разработчик может захотеть его использовать.
Он также должен упомянуть о любых крупных предметах в чванстве и ссылки на связанные темы. Поскольку документация для swagger является новой, вам может потребоваться создать начальные версии этих связанных тем.
Введение - Установка - Настройка (разработка в Node.js)
Вступление:
Swagger - это набор правил / спецификаций для формата, описывающего API REST. Он обеспечивает мощную и активно развитую экосистему инструментов вокруг этой формальной спецификации, такой как генераторы кода и редакторы. Лучшая часть Swagger заключается в том, что документация методов, параметров и моделей тесно интегрирована в код сервера, позволяя API всегда оставаться в синхронизации. Вот ссылка, дающая краткий обзор того, что такое чванство: начало работы.
Технические характеристики написания:
Спецификации могут быть записаны в JSON или YAML. И поэтому мы делаем файл swagger.json или swagger.yaml соответствующим образом. Для создания файла можно использовать онлайн-редактор. Вот ссылка, описывающая синтаксис спецификаций: http://swagger.io/specification/
Способы использования swagger:
- API-первый подход (подход сверху вниз): используйте редактор swagger → Определите определения чванства → Используйте swagger-codegen и swagger-ui для создания API-интерфейсов
- Первый подход к сервису (подход 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.