Установка swagger на локальной машине
Русские Блоги
Запустите Swagger-ui локально, чтобы просмотреть файл Json, экспортированный Swagger
Когда мы получаем Json-файл определения API, экспортированный Swagger, предоставленный другими партнерами по проекту, очень болезненно напрямую использовать текстовый редактор для открытия локальной среды просмотра. Здесь я покажу вам, как использовать git, node и npm, чтобы быстро создать локальную службу и просмотреть файл json, экспортированный с помощью swagger.
полагаться
git-любую версию git можно использовать для получения последней программы swagger-ui из github
использоватьОфициальный список рекомендацийВерсия node.js будет более стабильной.
установка
Здесь я рекомендую использовать homebrew для установки git и node, npm.
Или через рубин, который идет с Mac:
Или укажите рубиновый путь:
Добиться установки доморощенного.
Протяните код swagger-ui через git и запустите проект:
Позже вы можете увидеть знак успешного запуска и открыть http: // localhost: 3200 /, чтобы увидеть, что служба swagger-ui запущена локально.
Мы видим, что исходный адрес json, просматриваемый в swagger-ui, должен быть адресом json, который может быть просмотрен веб-сервером, предоставленным на сервере. Для обеспечения локального просмотра веб-сервер должен быть запущен локально.
Рекомендуется использовать http-сервер напрямую:
Затем введите каталог json-файла, который необходимо просмотреть, предполагая, что мы хотим просмотреть файл /path/Downloads/swagger.json, затем выполните:
Таким образом, http-сервер можно запустить локально.
Введите на странице Swagger-ui: http: // localhost: 8080 / swagger.json, чтобы просмотреть нужный нам файл swagger. 
Руководство Swagger UI
Swagger UI предоставляет Фреймворк, который читает спецификацию OpenAPI. и создает веб-страницу с интерактивной документацией. В этом руководстве показано, как интегрировать документ спецификации OpenAPI в интерфейс Swagger.
Концептуальный обзор OpenAPI и Swagger можно посмотреть в разделе Знакомство со спецификациями OpenAPI и Swagger. Пошаговое руководство по созданию документа спецификации OpenAPI смотрим в Обзоре руководства OpenAPI 3.0.
Обзор Swagger UI
Прежде чем мы углубимся в Swagger, нужно прояснить ключевые термины.
Swagger
OpenAPI
Официальное название спецификации OpenAPI. Спецификация OpenAPI предоставляет набор свойств, которые можно использовать для описания REST API. Рабочий, валидный документ можно использовать для создания интерактивной документации, создания клиентских SDK, запуска модульных тестов и многого другого. Подробности спецификации можно изучить на GitHub по адресу https://github.com/OAI/OpenAPI-Specification. В рамках инициативы Open API с Linux Foundation спецификация OpenAPI направлена на то, чтобы быть независимой от производителя (многие компании участвуют в ее разработке).
Swagger Editor
Онлайн-редактор, который проверяет документацию OpenAPI на соответствие правилам спецификации OpenAPI. Редактор Swagger помечает ошибки и дает советы по форматированию.
Swagger UI
Swagger Codegen
Знакомство со Swagger при помощи Petstore
Чтобы лучше понять интерфейс Swagger, давайте рассмотрим пример Swagger Petstore. В примере Petstore сайт генерируется с помощью Swagger UI.
Конечные точки сгруппированы следующим образом:
Авторизация запроса
Прежде чем делать какие-либо запросы, нужна авторизация. Нажимаем кнопку Authorize и заполняем информацию, требуемую в окне «Авторизация», изображенном ниже:
Пример Petstore имеет модель безопасности OAuth 2.0. Код авторизации только для демонстрационных целей. Нет никакой реальной логики авторизации этих запросов, поэтому просто закрываем окно Авторизации.
Создание запроса
Теперь создадим запрос:
Пользовательский интерфейс Swagger отправляет запрос и показывает отправленный curl. Раздел Ответы показывает ответ. (Если выбрать JSON вместо XML в раскрывающемся списке «Response content type», формат ответа будет показан в формате JSON.)
Проверка создания питомца
Примеры сайтов с документаций по Swagger UI
Прежде чем мы перейдем к другому API с этим пособием по Swagger (кроме демонстрации Petstore), посмотрим на другие реализации Swagger:
Некоторые из этих сайтов выглядят одинаково, но другие, такие как The Movie Database API и Zomato, были легко интегрированы в остальную часть их сайта документации.
👨💻 Практическое занятие: Создание спецификации OpenAPI в Swagger UI
На этом занятии мы создадим документацию в Swagger UI в спецификации OpenAPI. Если вы используете один из предварительно созданных файлов OpenAPI, вы можете увидеть демонстрацию того, что мы создадим здесь: OpenWeatherMap Swagger UI или Sunrise/sunset Swagger UI).
Для интеграции спецификации OpenAPI в Swagger UI:
Установка и настройка Swagger Validator
Что? Зачем?
Что такое валидатор и как он работает?
Для того, чтобы наша документация была валидной у Swagger есть валидатор. Да, json схему OpenAPI спецификации можно провалидировать спокойно онлайн на нескольких ресурсах (тыц, тыц, тыц), но гораздо удобнее, когда такой инструмент есть здесь и рядом. В документации Swagger в правом нижнем углу есть значок-изображение, который сигнализирует о валидности схемы, которая была разработана.
По-умолчанию, валидация происходит благодаря онлайн валидатору. Он обращается по урлу к нашей документации, валидирует и сообщает ответ в виде изображения. При клике по этому изображению происходит переход на страницу валидатора с дебаг информацией, где отображаются ошибки или сообщение “всё ок”.
Почему не работает онлайн валидатор
Попытка установить пакет без использования докера
А что делать если проект не упакован в докер? И тут начинаются танцы с бубном. Сами танцы я пропущу и перейду сразу к бубнам. Для запуска валидатора необходимо установить Apache Maven и java. И, конечно же, выкачать сам пакет:
Работает, работает да не работает
С этим нам помог инструмент swagger-merger. Здесь всё просто: устанавливаете пакет и выполняете команду
Мы для удобства добавили скрипт в composer.json
Отображение статуса валидации
Подход, который я описал выше удобен для локальной разработки когда есть возможность обратиться к валидатору, передав ему ссылку на документацию. Но ведь гораздо удобнее чтобы результат работы валидатора отображался сразу в схеме. И тут ещё немного работы осталось.
Нам необходимо в скрипте инициализации Swagger на странице документации указать URL валидатора:
Решили указать не тот URL, на котором запущен сам валидатор, а наш кастомный. Для обработки запроса к нему есть 2 пути: через nginx и обычными средствами php.
Для получения дебаг-информации код будет приблизительно следующим:
На этом всё. Открывая страницу нашей документации в правом нижнем углу должно отображаться изображение со статусом валидации.
Надежды на светлое будущее
Этот тернистый путь мы проделали сами и надеемся, что вам он поможет сэкономить время, деньги и терпение.
Настройкой сервера валидатора и написанием кода занимался не я один, а с помощью Михаила Даниленко и Ольги Демчишиной.
Установка и настройка Swagger
Описание
Swagger — это технология, которая позволяет документировать REST-сервисы. Swagger поддерживает множество языков программирования и фреймворков. Также Swagger предоставляет UI для просмотра документации.
В данной статье я расскажу как подключить Swagger к Maven проекту, в котором реализованы REST-сервисы с помощью спецификации JAX-RS — RESTEasy. В статье будет расписано подключение Swagger к проекту, использование документирования REST-сервисов с помощью аннотаций, описание визуализации документации через Web UI.
Подключение Swagger к проекту
Подключение Maven зависимостей
Для начала мы должны добавить в проект Maven зависимость Swagger’а. Так как мы будет подключать Swagger к RESTEasy, то добавим соответствующую зависимость.
На момент написания мануала актуальной версией является 1.5.6.
Нужно учесть, что у Swagger есть legacy Maven репозиторий. У lagecy репозитория groupId=com.wordnik. Нужно это учесть и не перепутать зависимости!
Более подробно можно прочитать тут.
Настройка проекта
Далее нам необходимо подключить в проект необходимых слушателей (listeners), чтобы Swagger мог автоматически определять аннотации и генерировать документацию.
Мы производили настройку с помощью потомка класса javax.ws.rs.core.Application.
Настройка будет выглядеть так:
Более подробно о других методах подключения можно почитать тут.
Настройка Swagger
Далее необходимо установить настройки самого Swagger. Мы это сделали в конструкторе того же наследника класса Application.
Более подробно о других методах настройки можно прочитать тут.
Аннотации
Для начала я опишу аннотации, которые являются обязательными для правильного документирования и корректного отображения REST-сервисов на Swagger-UI.
Для того, чтобы swagger определил, что в классе находятся REST-сервисы, этот класс должен быть помечен аннотацией @Api. В параметрах данной аннотации можно указать название раздела, в котором будут находится REST’ы в UI, и указать описание данного раздела.
Например:
@ApiOperation
Аннотацию @ApiOperation необходимо указывать над методом REST-сервиса. Также в её параметрах можно указать описание сервиса.
Другие аннотации
Для явного указания хидеров, которые являются обязательными для конкретного сервиса можно использовать аннотацию @ApiImplicitParam
Для явного указания объекта ответа можно использовать аннотацию @ApiResponse. Это будет полезно, если в качестве ответа от сервера REST возвращает объект Responce.
Более подробную информацию обо всех аннотациях можно найти тут.
WEB UI
Чтобы установить url по умолчанию необходимо отредактировать исходный код файла index.html
После чего мы увидим документацию наших REST-сервисов. Делать запросы к REST-сервисам можно прямо из UI.
В случае если Swagger выдаст ошибку can`t fetch нужно будет производить настройку CORS headers в сервере, на котором задеплоено наше приложение, нам нужно добавить header Access-Control-Allow-Origin:*
Пример отображения REST-сервисов на UI:
Список REST сервисов на Web-UI:
Форма детальной информации о REST-сервисе и возможности отправки запроса.
Документирование #микросервисов
Оригинальная статья является размышления на тему почему документация в мире микросервисов критично необходима и как ее можно создавать и публиковать используя swagger. Пошаговой инструкцией по настройке она точно не является.
Вступление
Несколько месяцев назад один из наших бекенд разработчиков интернов получил задачу — разработать новый простой сервис. Сервис должен был генерировать емайл отчеты о пользовательской активности. В задаче не было ничего сложного и у интерна все получилось. Однако через несколько недель мы захотели включить в отчет более детальную информацию о некоторых конкретных пользователях. Я решил обновить этот сервис самостоятельно. “Просто получи данные из нашего пользовательского сервиса и вставь их в емайл”, — думал тогда я.
На это у меня ушло несколько часов, и даже пришлось подключить двоих других разработчиков только для того, чтобы найти правильные REST endpoints и необходимые мен структуры. “Никогда больше. Должен быть более правильный метод это сделать…”, — крутилось у меня в голове все это время.
Микросервисная архитектура подразумевает набор самостоятельных сервисов, которые общаются друг с другом, а для конечного пользователя выглядит как единая программа. Один из самых популярных протоколов для обмена сообщениями между микросервисами — это REST. Проблема в том, что REST не является само описательным протоколом. Это значит, что клиент должен знать конкретную комбинацию URL, HTTP метода и формата ответа. В некоторых случаях необходимо также знать также формат тела запроса. Обычно реализация REST интерфейса базируется на общих принципах и традициях, принятых в вашей организации. В любом случае, REST endpoints всегда должны быть описаны в одном конкретном документе, доступном для всех остальных разработчиков. О том, как и где хранить, мы поговорим чуть позже, а пока давайте обсудим основы — формат документации.
Swagger
Документацию должно быть легко читать, писать, парсить, генерировать, исправлять, обновлять и прочее. Решение должно быть настолько простым, чтобы даже самые ленивые разработчики им пользовались. После небольшого исследования мы в Ataccama решили использовать Swagger для документирования наших REST APIs.
Swagger — это фреймворк и спецификация для определения REST APIs в формате, дружественном к пользователю и компьютеру (в нашем случае JSON или YAML). Но Swagger — это не просто спецификация. Основная его мощь заключается в дополнительных инструментах. Для Swagger существует огромное количество бесплатных утилит (как официальных, так и написанных сообществом), которые могут сделать жизнь (вашу и ваших коллег) немного более счастливой. Вы можете установить все это на свои собственные сервера и посмотреть, как это работает — например, попробовать работу с браузером документов или Swagger онлайн-редактором.
Как мы это делаем?
Если вы тоже думаете, что Swagger — это здорово, то читайте дальше. Сейчас будет немного подробностей о том, как мы используем его в Ataccama, в таинственном мире микросервисов.
У каждого микросервиса в определенной папке лежит файл со Swagger описанием и хранится это все прямо в git-репозитории. Описания могут быть как сгенерированы при помощи Swagger generator, так и записаны туда вручную. Прелесть заключается в том, что для записи определений используются JSON и YAML форматы. Их легко распарсить, и во время сборки проекта мы можем автоматически проверять соответствие REST endpoints и документации. Несоответствия будут генерировать предупреждения, и тем самым стимулировать разработчика поддерживать документацию в актуальном состоянии.
Хранение документации внутри микросервиса позволяет нам отображать её в любое время прямо из этого микросервиса в процессе работы. Это помогает тестировать и отлаживать REST endpoints в процессе развертывания сервиса на собственной машине. А ещё у Swagger есть инструмент с веб интерфейсом для тестирования REST endpoints.
Поскольку каждый микросервис предоставляет собственную документацию, мы можем настроить специальную задачу для Дженкинса (или любого другого CI сервера), которая сгенерирует полную документацию для всего проекта. Эта задача собирает Swagger файлы из всех микросервисов, производит некоторые минимальные модификации (дедупликация, удаление ненужных атрибутов) и на выходе генерирует единый Swagger файл, содержащий полную актуальную информацию для всего проекта.
Публикация документации.
Централизованное хранение и редактирование документации — это только первый шаг. Следующий — сделать ее доступной для всех разработчиков, тестеров и остальных заинтересованных людей в компании. И Swagger UI — это именно то, что вам для этого понадобится. При помощи небольшой JavaScript библиотеки Swagger UI генерирует HTML элементы для всех ваших REST endpoints, которые далее можно упорядочивать с помощью HTML разметки.
По умолчанию Swagger UI подгружает собственный Swagger файл с примерами. Все остальные API должны быть загружены вручную. Но конфигурация занимает всего несколько секунд.
Теперь у нас есть сгенерированная документация в читабельном виде. Время отправить её на сервер.
Некоторое время назад мы в Ataccama начали использовать Docker, и поэтому подумали, а почему бы не упаковать всю документацию в отдельный докер контейнер, загрузить его в наш частный репозитарий, а потом задеплоить в докер кластер? Дженкинc может это сделать буквально за несколько секунд. Как результат мы всегда имеем обновленную документацию доступную к просмотру через браузер.
Кроме того, использование докера дает нам еще несколько преимуществ:
Каждый разработчик может просто загрузить документацию и запустить её на собственном компьютере всего одной командой.
И это только начало.
Это только общая идея того как мы генерируем документацию для REST endpoints и публикуем ее при помощи докера для наших микросервисов. К сожалению, синхронный REST это не все, что нам надо документировать в этом лабиринте микросервисов. В какой-то момент хочется перейти на более продвинутые системы общения, на асинхронный обмен сообщениями, очереди, подписки на события и прочее.
Несмотря на расхваливание Swaggerа мы все еще не нашли удобного метода документирования асинхронных сообщений. По факту, в Атаккаме мы недовольны нашим текущим решением и все еще пытаемся найти что-нибудь более простое и красивое для описания очередей сообщений и их структур. Если у вас есть идеи как это можно сделать лучше, пишите в комментариях. Любые интересные идеи приветствуются.
Автор Lubos Palisek
Backend software developer in Ataccama. Greedy for new cloud based technologies and ideas.
Ataccama Corporation – международная компания, производитель программного обеспечения, специализирующаяся в области решений по управлению качеством данных, управлению мастер-данными и управления данными предприятия (data governance), решениями которого уже воспользовались более 250 компаний, начиная от предприятий среднего размера и заканчивая международными компаниями из различных отраслей.
Все ваши вопросы и рекомендации с удовольствием переведу автору.