Благодаря ему пользователи и машины лучше понимают возможности REST API без доступа к коду. С помощью Swagger можно быстро создать документацию и отправить ее другим https://deveducation.com/ разработчикам или клиентам. Ручное формирование документации — утомительное занятие. С его помощью на основе кода можно автоматически сгенерировать спецификации API.
Далее мы используем response specification — это особенность REST Assured. И валидируем сразу ответ, проверяем, что код — 200. Есть API-клиент, есть вызов Story API и метод getInventory. Для того чтобы написать шаблоны, нам нужны переменные. В документации OpenAPI Generator описано, как их получить.
В нем представлены образцы Swagger Core из библиотеки Java. Каждый образец содержит файл Readme, в котором подробно описано, как его запускать и что проверять. Чтобы пользоваться вторым подходом, нужно знать синтаксис Swagger. Описания можно готовить в формате YAML/JSON. Можно упростить эту задачу, используя Swagger Editor.
API дает возможность осуществлять взаимодействие с различными сервисами и приложениями, используя специальные запросы и ответы. Здесь встроен экземпляр Swagger UI, который показывает файл OpenAPI для OpenWeatherMapAPI. Выглядит как неплохо сверстанная документация, хотя в оформлении остались дефолтные элементы. При большом желании их тоже можно поменять. Гораздо важнее, что можно автоматизировать процесс обновления такой внешней документации.
Мы можем проверять в тестах, что наш ответ после запроса соответствует определённой модели, которая описана в спецификации. Но в реальности это очень маленькое, узкое покрытие. Мы проверяем только модели и не проверяем значения.
Второй способ — использовать специализированные средства для написания спецификаций. Вы в нем описываете вашу спецификацию, там есть удобный редактор, который сразу её валидирует. В правой части она у вас отображается в красивом виде.
Как Построить Процесс
Скоро вы обнаружите, что в вашем API есть внутренние операции, о которых вы не знали, но которые тоже надо тестировать. Самое приятное, что всё это легко исправляется. Таким образом, у нас было очень много автотестов сомнительного качества. Они были понятны только тем, кто их пишет, тестовые клиенты моментально устаревали, а поддерживать их было некому. И главное, разработка не участвовала в тестировании. Примеры описания параметров запросов и формат ответов можно найти здесь.
Итак, мы получили все переменные, написали все шаблоны и соответственно сделали pull request в Swagger Codegen. Когда мы только всё начинали, мы рассматривали множество клиентов в Swagger Codegen, написанных под разные языки, но ни один нас не устроил. Все эти клиенты очень жёстко привязаны к документации. В них мало точек расширения, и они не рассчитаны на то, что наша спецификация будет меняться. Мы решили, что напишем свой API-клиент, который будет обладать всеми необходимыми для нас возможностями. Например, вот доклад технического писателя из «Яндекса» о том, что такое вообще API и как работать со Swagger.
Данная спецификация использовалась только для Swagger UI, а мы хотим получить клиент. И мы можем получить что-то невразумительное. Вместо методов вашего тестового клиента у вас будут route1, route2, route16. Три года назад картина у нас была следующая. У нас были автоматизаторы тестирования, которые имели достаточно стандартный подход и писали автотесты на Apache HTTP-клиенте. И у нас были разработчики, которые писали в основном юнит-тесты, интеграционные тесты.
Как Выглядят Сайты С Документацией Swagger Ui
Мы этот параметр используем в тесте, но его уже нет в клиенте. Для каждого из методов HTTP Swagger позволяет описать параметры запросов и формат ответов. У нас собрался build, и запустился Swagger-diff, и мы уже заранее знаем на этом этапе, сломалась ли обратная совместимость и изменилось ли что-нибудь.
Мы можем красить construct в красный цвет и тем самым стимулировать разработчиков писать тесты. Так же выглядят и теги — это группа операций. Мы можем понять, сколько операций покрывается, сколько вообще не покрыты. Ещё есть фильтры по условиям, можем посмотреть, какие условия не покрываются совсем. После генерации у нас в папке target возникают такие тесты.
Самый простой способ — написать её в текстовом файлике. Давайте подробнее разберём, что она собой представляет. Мы там ставим версию нашего API, устанавливаем хосты, базовые пути, схемы и прочее. Также у нас есть блок с описанием всех возможных операций, в которых мы указываем параметры и все возможные ответы. У нас во всех проектах есть спецификации. В основном это спецификации двух версий — это OpenAPI-спецификации v1.0 и OpenAPI-спецификации v2.zero.
Их могут писать автоматизаторы тестирования и понимать ручные тестировщики и разработчики. Всю эту красоту мы вынесли в шаблон проекта с автотестами. В REST Assured нетипизированные параметры. У Retrofit ответ всегда мапится на ответ из спецификации по умолчанию.
Как Встроить Swagger Ui В Существующий Сайт
Ещё один плюс — эти клиенты легко добавлять. Вам надо только добавить набор mustache-шаблонов, и у вас готовый клиент. И третья очень крутая фича — эти клиенты очень легко кастомизировать. Достаточно добавить свои шаблоны, которые просто будут использоваться при генерации. В данной публикации рассмотрим подробнее Swagger, позволяющий создавать, документировать и тестировать API. С помощью Swagger можно узнать доступные эндпоинты, параметры запросов и формат ответов.
А некоторые вообще не понимали, зачем нужны автотесты, так как считали, что ничего не сломается. Я занимаюсь автоматизацией тестирования в Яндексе с 2013 года. Из них более четырёх лет автоматизирую тестирование REST API-сервисов. Для тестировщиков головная боль — именование тестовых методов и тестовых классов. У нас единое наименование на основе OpenAPI-спецификации. Из-за этого единообразия мы пришли к тому, что наши автотесты могут писать все.
Это обеспечивает понятность и консистентность описания API и позволяет разработчикам эффективно использовать API в своих приложениях. Мы знаем, какие операции у нас полностью покрыты, какие частично, какие вообще не покрыты. Также, если мы рассмотрим подробнее операцию, то увидим условия. Эти условия формируются на основе OpenAPI-спецификации. Например, если в OpenAPI-спецификации есть пять кодов ответа, то сформируется пять условий на эти коды ответа. В нашем примере видим, что у нас не проверяются все значения параметра status, мы не используем значение enum-а sold.
На GitHub создали project-template, где указали клиент, модуль с тестами, настроили генерацию. Если нам нужен проект автотестов на какой-то новый сервис, мы берём и наследуемся от этого шаблона. Чтобы проект заработал, нам достаточно поменять значения двух property, и получаем готовые тесты и сгенерированные клиенты.
- Мы можем попробовать сгенерировать assertions на модели ответов с помощью плагина.
- На самом деле мы пытаемся генерировать клиент из спецификации, которая на это не рассчитана.
- Нам пришла идея, почему бы не использовать свои темплейты.
- Мы устанавливаем в Request specification все возможные параметры со значениями, которые описаны у нас в спецификации.
- Данная спецификация использовалась только для Swagger UI, а мы хотим получить клиент.
Если это, например, JSON, то мы проверяем только поля и что они соответствуют схеме. Но нам бы хотелось понимать, что ответ нашего запроса правильный. Необходимо понимать, с каким опытом мы пришли к этой задаче. Давайте поговорим об эволюции автотестов, которую мы прошли. Изначально мы писали автотесты на Apache HTTP shopper. Поняв, что дублируем много кода и он очень громоздкий, мы написали свою обвязку над HTTP client-ом.
В 2015 году проект Swagger сделали открытым и передали OpenAPI Initiative. Теперь сама спецификация называется OpenAPI. Swagger — инструментарий для работы с OpenAPI, название которого используется в коммерческих и некоммерческих продуктах.
Надо просто запустить нашу генерацию с флагом DebugOperations, и в итоге мы получим переменные для операций, которые будем использовать в шаблонах. Например, есть версия v1.x, v2.x и vN.x. То есть у нас получается два , для версии v1 и для версии v2.
Давайте разберёмся теперь с генерацией клиента. В opensource есть два больших, достаточно популярных проекта. Это Swagger Codegen, он на данный момент поддерживается компанией SmartBear. И OpenAPI Generator, тоже opensource-проект, но он поддерживается комьюнити.
No Comments