Как работать со сваггером

Тестирование API с помощью Swagger: особенности и преимущества

API (Application Programming Interface) — это набор процедур, протоколов и инструментов, позволяющих разным программным приложениям общаться между собой. API дает возможность осуществлять взаимодействие с различными сервисами и приложениями, используя специальные запросы и ответы.

Наиболее популярные и эффективные инструменты для тестирования API:

• Postman — это инструмент для тестирования API, позволяющий создавать, отправлять и тестировать HTTP-запросы и проверять ответы на них.
• Swagger — это инструмент для документирования и тестирования API, позволяющий автоматически создавать документацию API из описания структуры API в формате YAML или JSON файла.
• SoapUI — это инструмент для тестирования веб-сервисов, позволяющий создавать и выполнять тесты на протоколе SOAP.

Рекомендуем публикацию по теме

• Как тестировать веб-сервисы с помощью SoapUI смотреть 129 мин

• Fiddler — это инструмент для анализа и отладки HTTP-трафика между веб-браузером и веб-сервером. С точки зрения тестирования API Fiddler позволяет перехватывать, анализировать и модифицировать HTTP-запросы и ответы, передаваемые между клиентом и сервером. Это позволяет тестировщикам осуществлять валидацию запросов и ответов, проверять правильность передачи параметров, куки и другие элементы запросов, отслеживать проблемы с трафиком, а также выявлять и локализовать проблемы с API.
• JMeter — это инструмент для тестирования производительности и функциональности программного обеспечения, который может использоваться для тестирования API. С точки зрения тестирования API, JMeter является инструментом, позволяющим создавать запросы к API, анализировать ответы и оценивать производительность и функциональность API. JMeter может использоваться для создания нагрузки на API, чтобы измерить производительность, время ответа и другие метрики, которые помогут обнаружить ошибки в API и улучшить его производительность и функциональность.

Рекомендуем публикацию по теме

• QA: Основы нагрузочного тестирования с инструментом Jmeter смотреть 66 мин

Вышеперечисленные инструменты позволяют тестировщикам эффективно и быстро проверять API на разных этапах разработки, чтобы обеспечить его соответствие требованиям и качеству.

В данной публикации рассмотрим подробнее Swagger, позволяющий создавать, документировать и тестировать API. С помощью Swagger можно узнать доступные эндпоинты, параметры запросов и формат ответов.

О Swagger

Swagger разработан компанией Reverb Technologies, основанной в 2010 году в Миннеаполисе, США. Основателями компании были Тони Тамбурино (Tony Tambourine), Райан Дювелл (Ryan Duell) и Ник Селлер (Nick Sutterer).

Swagger создан в целях облегчения работы разработчиков API и обеспечения большего взаимодействия между разработчиками и потребителями API. В 2015 году Swagger был перенесен в сообщество OpenAPI Initiative, которое является частью Linux Foundation, где его разработка и поддержка продолжаются по сей день.

Преимущества и особенности Swagger:

• Легкость использования: Swagger имеет простой и легкий интерфейс, позволяющий разработчикам быстро и легко создавать и документировать API.
• Автоматическое поколение документации: Swagger позволяет автоматически создавать документацию для API с использованием стандарта OpenAPI. Это позволяет потребителям API быстро и легко понять, как взаимодействовать с API и использовать его функциональность.
• Поддержка различных языков программирования: Swagger поддерживает многие языки программирования, что позволяет разработчикам использовать его для документирования API на любом языке программирования.
• Поддержка открытых стандартов: Swagger основан на стандартах OpenAPI, которые поддерживаются большим количеством инструментов и платформ, что позволяет разработчикам использовать его с любым другим инструментом или платформой, поддерживающими стандарты OpenAPI.
• Тестирование и валидация API: Swagger позволяет разработчикам тестировать и валидировать API, обеспечивая большую надежность и качество работы API.
• Расширяемость Swagger имеет открытый код и активное сообщество разработчиков, что позволяет им расширять и настраивать его под свои нужды.

Для каждого из методов HTTP Swagger позволяет описать параметры запросов и формат ответов.

Например, для метода GET можно описать параметры запросов, такие как query string parameters, headers, или path parameters, и формат ответа, такой как JSON или XML. Аналогично Swagger позволяет описывать параметры и формат ответов для методов POST, PUT и DELETE. Это обеспечивает понятность и консистентность описания API и позволяет разработчикам эффективно использовать API в своих приложениях.

Примеры описания параметров запросов и формат ответов можно найти здесь.

Примеры методов

POST метод (создание объекта):

Результат после отправки запроса:

Что думаю о Swagger

Одна из самых бесполезных вещей в айти — это Swagger. Так называется система, которая отображает REST-апихи в JSON-файле. Идея хорошая, но на практике вымораживает мозг. Давно порывался написать о ее минусах, и вот на днях опять подгорело.

Если вы внедряете в проекте Swagger, то скорее всего, занимаетесь ерундой. За все годы работы мне приходилось внедрять его четыре раза, и каждый раз я не видел от него пользы. Так, болтается какая-то хрень сбоку, отнимает время и ресурсы, никто ее не смотрит. Поставьте скрипт аналитики и убедитесь, что в нем от силы одно посещение в день.

Swagger это порождение мира node.js, столь мне отвратного. Это папка node_modules с миллионом микро-файлов, хрупкие сборки и прочие фу. К счастью, появились докер-образы, но и они не без греха. Так, образ swagger-ui нельзя запустить в read-only файловой системе. Если у вас Кубернетис, придется выкручиваться.

Усилия, направленные в русло Swagger, напоминают строительство пирамид. Масштабно, неэффективно и никому не нужно. Верный признак ущербности в том, что со всех сторон плодят еще более не нужные утилиты: убогий онлайн-редактор, CLI и, конечно, ОБЛАЧНУЮ учетную запись. Для утилиты, которая по JSON рисует HTML.

Те, кто топят за Swagger, не понимают, как устроена документация в фирмах. Дело в том, что JSON не может нормально передать текст, он для этого не предназначен. Использовать для документации язык, в котором нет мульти-строк, средств акцента, ссылок и прочего — это прохладная идея.

Нормальная документация — это семейство markdown- или asciidoc-файлов, объединенных в проект. Человек садится за редактор и пишет текст ручками. Расставляет акценты, ссылки, сноски. Это трудная работа, но только так получается достойная документация.

Конечно, я за то, чтобы процесс был автоматизирован. Приложение может сбрасывать JSON-схемы в файлы, которые затем подхватит сборщик документации. Но текст должен писать человек, и обязательно упомянуть все неочевидности, которые найдутся при работе с апихой. А их, как правило, вагон: эту апишку можно вызвать только при таком условии, параметры зависят друг от друга, и так далее. Описание одного только поиска может занять два экрана с примерами. JSON-схема не передаст всех нюансов.

Верный признак того, что Swagger это ущербная технология — им не пользуются самостоятельные компании. За всю карьеру я ни разу не видел, чтобы условный Гугл, Яндекс, Амазон и прочие показывали документацию через Swagger. В фирмах разный подход, но как правило это HTML с написанным человеком текстом. Вот несколько примеров:

Кто там еще? Вконтакт, Dropbox, банки (Тинек, Сбер)… ни одна значимая фирма не пользуется Сваггером. По моим меркам это был бы позор уровня студента.

Стандартный шаблон Сваггера ужасен. Взгляните на официальное демо:

Тут красненький, тут желтенький, зеленый, выпадашечки, блин, цирк. Школьное поделие, а не документация. Этот шаблон не вписывается ни в один дизайн, каждый элемент чужероден. Нужно несколько дней на то, чтобы сверстать свой шаблон. Предлагать клиентам Сваггер — значит заведомо не уважать их.

Кроме убогого шаблона, Swagger предлагает утилиту для генерации кода приложения. Давайте честно: кто захочет строить проект на базе кодогенерации, написанной неизвестно кем? Этот код однозначно уйдет в урну. Конечно, генерация пригодится студентам для курсовой работы по предмету “введение в веб-разработку”, но и только.

В общем, прекратите страдать фигней. Хотите нормальную документацию — поднимайте проект на Asciidoc, Wiki, GitBook, что угодно. Это трудно и требует навыков выражать свои мысли понятно. Может, пока апиха в разработке и меняется каждые два дня, нет смысла писать документацию. Но не вываливайте на клиентов интерфейс Сваггера. В нем отчетливо слышна машинная природа, и по всем признакам ясно, что эта страница не для людей.

Нашли ошибку? Выделите мышкой и нажмите Ctrl/⌘+Enter

У нас бэк генерит swagger страничку с описанием api, фронтендеры рады, бэкендеры не напрягаются 🙂

Ну как минимум google рекомендует использовать тулы базирующиеся на OpenAPI а так же предлагает свой транслятор к swagger (так что я бы не стал говорить за все)
https://googleapis.github.i. .

Не совсем понятен хейт, тк swagger дает вам бесплатную документацию API (без необходимости лезть в код, особенно если у вас к нему нет доступа) используя ваши типы и все что для этого нужно — подключить библиотеку. Понятно что написаная человеком документация гораздо лучше сгенерированной, но как мне кажется одно органично дополняет другое

Мне близка ваша мысль о том, что Сваггер — признак нездорового проекта. Я обычно встречаю его в компаниях, которые занимаются постоянной гонкой, где нужно вот уже вчера зарелизить три суперсрочных фичи, бекендеры только что вывалили в сваггер кучу каких-то энпоинтов, которые никто не понимает как работают, но делай фронт, по ходу разберёшься.

А ещё любимая тема — автогенерация api-файлов на фронтенде по сваггеру. Неважно что нам нужно десяток эндпоинтов для админки, в сваггер.джейсоне их две сотни, половина из который устарели или сделаны на будущее — генерируй монструозный файл и используй только нужное.

От не правильного версионирования API, а так же от глупых разработчиков (по принципу херак-херак в продакшен) вас никто не спасет. Все то же я наблюдаю и в десятках других проектов без swagger’a документации и т.д

Схема сваггера (или OpenAPI) сама по себе штука неплохая, просто не нужно воспринимать её как end-user документацию. Это именно схема — описание типов данных и эндпоинтов (как WSDL в SOAP или proto файлы в gRPC).

В отличии от маркдауна, OpenAPI схема пишется очень быстро (или вовсе генерируется автоматически), её все понимают, её проще поддерживать, а её строгость позволяет навернуть сверху некоторую интересную автоматизацию, в частности:

1. Клиенты могут автоматически сгенерировать Mock-сервер, не дожидаясь готовности сервиса;
2. В интеграционных тестах запросы и ответы к тестируемым сервисам можно сравнивать со спецификацией и, таким образом, быть уверенным, что реализация соответсвутет спеке.

Большую подробную доку никто не отменял, но она пишется именно для конечных пользователей или конечного продукта как часть проектной документации. А для внутренних интеграций, где есть прямая связь между разработчиками, OpenAPI работает нормально.

Сваггер штука хорошая, позволяет держать по рукой всегда рабочие примеры взаимодействия с API. Swagger-UI использовать совсем не обязательно, open-api спеку можно скармливать в постман и подобные утилиты. Если относится к Swagger-UI как к полуфабрикату и встраивать его в человеческую документацию, то получается хорошо. Вот пример https://bambora.mpymnt.com/.

Swagger возможно, что неинтересно, но в данный момент он — legacy.
Интересно OpenAPI и технологии вокруг OpenAPI:
(1) удобный визуальный редактор для спеки
(2) возможность cгенерировать худо-бедно страничку с описанием REST API, понятную для бэкендеров и фронтендеров
(3) в качестве бесплатной «плюшки», через эту страничку, как правило, можно делать живые запросы и получать живые ответы, которые фронтендеры могут использовать для заглушек
(4) возможность через спеку валидировать запросы и ответы (что для среднего проекта и выше — must have фича).
Итого, OpenAPI в данный момент решает проблемы, который есть в реальности. Можно обсуждать лишь то, насколько удачно оно их решает :).
Ну и да, OpenAPI — это не про документацию. Это про представление API.

Разрешите с вами не согласиться. У меня абсолютно обратный опыт. А всё потому что я чаще всего API разрабатывают на ruby через DSL на grape, который отражает всё описание в swagge автоматомr.

Например код: https://github.com/dapi/tas.
Автоматом генерирует на swagger спеку и с которой можно обращаться через web:
https://tasky.online/api

И все это работает просто подключая пару модулей типа grape-swagger.

Не представляю себе как еще можно разрабатывать и документировать API. Я так понимаю в мире clojure это делается через compojure-api

Другое дело, когда код от API лежит в одном месте, а спека к swagger лежит в другом да ещё и пишется вручную на JSON. Вот этот я не понимаю. Спекая всегда будет отставать да и трудозатраты лишние.

согласен. мура это всё, пользоваться свагером не удобно не дружелюбно. тесты свагера как правило все кривые

Хз зачем им пользоваться, если в postman можно публиковать доку, которая автоматически обновляется

• Ivan Grishaev’s blog
• ivan@grishaev.me

Writing on programming, education, books and negotiations.

Что такое Swagger и как его использовать

Swagger — особый инструмент, автоматически документирующий интерфейс RESTful API вашего приложения.

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

Для доступа к Swagger необходимо в опубликованном приложении перейти в Preview и нажать на наименование нужного плана публикации (Deploy Plan).

Открывшееся окно содержит список доступных endpoints и методов, связанных с этими endpoints. Некоторые запросы доступны только определенным группам авторизованных пользователей (проверяется в Middleware модуля Auth для каждого конкретного запроса в разделе Endpoints). Для запросов, требующих авторизации, нужно получить Bearer Token.

Для получения токена можно обратиться к соответствующему эндпоинту прямо в Swagger (раздел Auth, запрос POST /auth).

Далее, нужно нажать Try it out и ввести логин и пароль пользователя, для авторизации и получения токена.

Нажав Execute будет отправлен запрос. В ответе запроса, если он успешен, нужно найти поле token, которое и будет содержать токен авторизованного пользователя.

Второй способ получения токена авторизованного пользователя заключается в том, что в сгенерированном приложении, отправив запрос и получив ответ на него, можно найти токен в теле самого запроса. Для этого:

1. Откройте инструмент разработчика в браузере (F12 в Google Chrome).
2. Отправьте запрос на сервер (например, обновив данные таблицы). Запрос должен быть отправлен авторизованным пользователем, у которого есть доступ к endpoint.
3. Открыть Network и выбрать соответствующий запрос.
4. Во вкладке Headers найти раздел Request Headers и в заголовке Authorization получить необходимый токен.

Передать токен в Swagger можно, нажав на Authorize и вставив скопированный токен.

Далее можно приступать к тестированию запросов. Для этого необходимо выбрать нужную группу и метод в ней. Нажав Try it out и заполнив входные параметры запроса, нажмите Execute, чтобы выполнить запрос.

Самый ожидаемый ответ, в случае правильной обработки запроса сервером, имеет код 200 и показывает то, как должна выглядеть структура ответа.

Остальные коды показаны скорее для некоторого ориентира на стандарт и применимы для автосгенерированных запросов.

• 401 — запрос не был выполнен успешно, так как необходимый токен авторизации отсутствует или не верен.
• 404 — запрос был обработан успешно, но искомый ресурс не найден.
• 422 — были переданы неправильные параметры на вход запроса.
• 500 — ошибка обработки запроса сервером.

Получение кастомных ошибок

Для кастомных БП и связанных с ними запросов возможно создавать свои коды ошибок с описанием с помощью блока Raise Error в редакторе БП. Пример такого БП ниже:

В этом случае, при неудачной попытке запроса к эндпоинту, связанному с БП выше, сервер выдаст ошибку 418, содержащую текст ошибки при выполнении блока DB: Create Candidate. Код ошибки в данном примере может любой, который задаст пользователь.

Примечание: HTTP код ошибки 418 I’m a teapot сообщает о том, что сервер не может приготовить кофе, потому что он чайник. Эта ошибка ссылается на Hyper Text Coffee Pot Control Protocol (гипертекстовый протокол кофейников) который был первоапрельской шуткой в 1998 году.

Swagger – умная документация вашего RESTful web-API — обзор Junior back-end developer-а для новичков

Команда, в которой я сделала свои первые шаги на поприще написания промышленного кода, занималась разработкой удобного API к функциональности программного продукта на C# (для удобства назовем его, скажем, буквой E), существовавшего уже много лет и зарекомендовавшего себя на рынке с весьма положительной стороны. И здесь вроде бы у юного падавана пока не должно возникать вопросов, однако же представим себе, что ранее вы, скорей всего, конечно, писали собственные web-API, но вряд ли для широкой аудитории, а значит жили по принципу «Сам создал – сам пользуюсь», и если вдруг кого-то бы заинтересовала функциональность вашего API, то вы, наверное, кинули бы ему pdf-файл с подробной инструкцией (по крайней мере я бы сделала именно так). «Где посмотреть функционал апи» — спросила я тимлида ожидая получить ссылку на текстовый документ. «Загляни в Swagger» — ответил он.

Постой, как так получается, что продукт успешно функционирует уже давно, а API вы к нему пишете только сейчас?

Все верно, как такового удобного публичного API у E до недавнего времени не существовало. Фактически вся работа происходила через web-интерфейс, а back-end состоял из множества внутренних микросервисов, с которыми невозможно было интегрироваться извне без четкого понимания внутренней бизнес-логики, уж не говоря о том, что сами они на значительную долю состояли из легаси. Нужно было обратить внимание на клиентов, которые хотят непосредственно напрямую взаимодействовать с сервером, а значит предоставить им красивое и удобное API. Что для этого потребуется? Все, о чем было написано чуть раньше – самим взять и наладить работу со всеми внутренними микросервисами, а также обеспечить удобную и красивую документацию, сделав это красиво, понятно, и самое главное – коммерчески успешно.

Хорошо, так что же есть такое Swagger и в чем его полезность миру?

По сути Swagger – это фреймворк для спецификации RESTful API. Его прелесть заключается в том, что он дает возможность не только интерактивно просматривать спецификацию, но и отправлять запросы – так называемый Swagger UI, вот так это выглядит:

Как мы видим – полное описание методов, включая модели, коды ответов, параметры запроса – в общем, наглядно.

И как это работает?

Отличное руководство для внедрения Swagger в ASP.NET Core
с нуля есть вот в этой этой статье.

Идея в конфигурации отображения с помощью специальных аннотаций у методов API, вот пример:

Swagger Codegen

Если очень хочется, то можно сгенерировать непосредственно клиента или сервер по спецификации API Swagger, для этого нужен генератор кода Swagger-Codegen. Описание из документации, думаю, пояснять не требуется:

This is the Swagger Codegen project, which allows generation of API client libraries (SDK generation), server stubs and documentation automatically given an OpenAPI Spec. Currently, the following languages/frameworks are supported:

• API clients: ActionScript, Ada, Apex, Bash, C# (.net 2.0, 3.5 or later), C++ (cpprest, Qt5, Tizen), Clojure, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell (http-client, Servant), Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-assured), Kotlin, Lua, Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations) Objective-C, Perl, PHP, PowerShell, Python, R, Ruby, Rust (rust, rust-server), Scala (akka, http4s, swagger-async-httpclient), Swift (2.x, 3.x, 4.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
• Server stubs: Ada, C# (ASP.NET Core, NancyFx), C++ (Pistache, Restbed), Erlang, Go, Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy, Play Framework, PKMST), Kotlin, PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), Rust (rust-server), Scala (Finch, Lagom, Scalatra)
• API documentation generators: HTML, Confluence Wiki
• Configuration files: Apache2
• Others: JMeter

Прочая информация, в частности инструкция по использованию, представлена здесь:
Общая информация

Заключение

Это был краткий наглядный обзор для начинающих разработчиков API, целью которого было предоставить общую картину того, что такое Swagger, зачем он нужен и какие он дает основные плюсы с моей личной точки зрения.