Что такое сваггер простыми словами

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:

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

Источник

Документирование #микросервисов

Оригинальная статья является размышления на тему почему документация в мире микросервисов критично необходима и как ее можно создавать и публиковать используя 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 компаний, начиная от предприятий среднего размера и заканчивая международными компаниями из различных отраслей.

Все ваши вопросы и рекомендации с удовольствием переведу автору.

Источник

Разработка REST-серверов на Go. Часть 4: применение OpenAPI и Swagger

Перед вами четвёртый материал о разработке REST-серверов на Go. Здесь мы поговорим о том, как можно воспользоваться OpenAPI и Swagger для реализации стандартизированного подхода к описанию REST API, и о том, как генерировать Go-код на основе спецификации OpenAPI.

Зачем это всё?

В первой части этой серии материалов, когда мы описывали REST API, я говорил о том, что описание этого API создано специально для нашего примера. Это описание представляет собой просто список методов (путей) с комментариями:

Было бы неплохо, если бы существовал стандартный способ описания API. «Стандартным» я называю такое описание, которое могло бы играть роль контракта между серверами и клиентами. Более того, стандартное описание API выглядело бы совершенно понятным для тех разработчиков, которые не знакомы с особенностями конкретного проекта. Такое описание, кроме того, могло бы быть понятным не только людям, но и машинам, что привело бы к возможности автоматизации различных задач, связанных с API.

Swagger и OpenAPI

Проект Swagger появился в 2011 году как IDL (Interface Description Language, язык описания интерфейсов) для описания REST API.

В 2014 году вышла версия Swagger 2.0, а в 2016 множество крупных IT-компаний объединили усилия в деле создании спецификация OpenAPI, жёстко стандартизированного варианта Swagger 3.0.

Официальный сайт Swagger и OpenAPI, https://swagger.io, поддерживает Компания SmartBear Software.

Во всех этих хитросплетениях технологий можно и запутаться. Легче всего разложить сведения о них в голове можно, если помнить о том, что OpenAPI — это современное название спецификации, а словом «Swagger» обычно называют инструменты, построенные на основе этой спецификации (правда, можно ещё столкнуться и с таким понятием, как «спецификация Swagger», особенно — если речь идёт о версиях Swagger, вышедших раньше, чем версия 3.0).

Создание сервиса системы управления задачами с применением OpenAPI

Начнём с повторения нашего любимого упражнения — с переписывания сервиса приложения для управления задачами. В этот раз мы воспользуемся OpenAPI и Swagger.

Для того чтобы это сделать, я почитал документацию OpenAPI 3.0 и воспользовался редактором Swagger для ввода спецификации в формате YAML. Это заняло некоторое время. В результате в моём распоряжении оказался этот файл.

Здесь components/schemas/Task представляет собой ссылку на модель Task :

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

Вся эта работа принесла плоды сразу же после её завершения. А именно — она дала мне приятно выглядящую, цветную документацию для API.

Фрагмент документации из редактора Swagger

Это — всего лишь скриншот. В настоящей документации можно щёлкать по её элементам, их можно раскрывать, можно видеть чёткие описания параметров запросов, ответов, JSON-схем и прочего подобного.

Представьте себе, что занимаетесь разработкой API в рамках приложения, предназначенного для управления задачами. На определённом этапе работы принято решение о том, что этот API можно опубликовать для того чтобы к нему можно было бы обращаться с клиентских систем различных видов (это могут быть веб-клиенты, мобильные клиенты и так далее). Если ваш API описан с использованием OpenAPI/Swagger, это значит, что у вас имеется автоматически созданная документация и интерфейс для клиентов, позволяющий им экспериментировать с API. Это вдвойне важно в том случае, если среди пользователей вашего API есть люди, не являющиеся программистами. Например, это могут быть UX-дизайнеры, технические писатели, продакт-менеджеры, которым нужно разобраться в API, но которые не особенно привыкли к самостоятельному написанию скриптов.

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

После того, как подготовлена спецификация API, можно взглянуть на дополнительные инструменты, имеющиеся в экосистеме Swagger. Например — это Swagger UI и Swagger Inspector. Спецификацию API можно даже использовать в роли вспомогательного инструмента при интеграции REST-сервера в инфраструктуру облачного провайдера. Например, в GCP имеется система управления API Cloud Endpoints, поддерживающая спецификацию OpenAPI. Она, кроме прочего, позволяет настраивать мониторинг и анализ опубликованных API. Описание API предоставляется этой системе с использованием OpenAPI.

Автоматическое генерирование базового кода для Go-сервера

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

В процессе работы я сделал некоторые выводы относительно ограничений такого подхода:

Инструмент swagger-codegen умеет ещё и создавать код клиентов, в том числе и на Go. Иногда это может оказаться очень кстати, но с моей точки зрения подобный код выглядит несколько запутанным. Он, как и в случае с серверным кодом, возможно, может сыграть роль хорошей отправной точки в деле написания собственного клиента, но механизм его автоматического создания вряд ли может стать частью некоего CI/CD-процесса.

Испытание альтернативных генераторов кода

Спецификации OpenAPI представлены в виде YAML (или JSON), их формат хорошо документирован. В результате неудивительно то, что существует далеко не один инструмент, позволяющий генерировать на основе этих спецификаций серверный код. В предыдущем разделе мы рассмотрели «официальный» генератор кода Swagger, но есть и другие подобные инструменты.

В случае с Go популярным инструментом такого рода является go-swagger. В README этого проекта есть следующий раздел:

Чем этот генератор отличается от генератора из swagger-codegen?

tl;dr В настоящий момент его главное отличие заключается в том, что он реально работает.

Проект swagger-codegen генерирует рабочий Go-код лишь для клиента, и даже тут он поддерживает лишь плоские модели. А код Go-сервера, сгенерированный swagger-codegen — это, в основном, нечто вроде кода-заглушки.

Я попробовал сгенерировать код сервера с помощью go-swagger. Так как код, сгенерированный этим средством, достаточно велик, я не привожу тут ссылку на него. Тут я лишь поделюсь впечатлениями от работы с go-swagger.

В первую очередь отмечу, что go-swagger поддерживает лишь спецификацию Swagger 2.0, а не более новую версию OpenAPI 3.0. Это довольно-таки печально, но я нашёл один онлайновый инструмент, который умеет конвертировать описания API, выполненные с использованием спецификации OpenAPI 3.0 в описания формата OpenAPI 2.0 (Swagger). Описание нашего API в формате Swagger 2.0 тоже имеются в репозитории проекта.

В серверном коде, сгенерированном go-swagger, определённо, реализовано больше возможностей, чем в коде, сгенерированном swagger-codegen. Но за всё надо платить. Дополнительные возможности означают привязку к особому фреймворку, разработанному создателями go-swagger. Сгенерированный код имеет множество зависимостей от пакетов из репозиториев go-openapi, в нём код из этих пакетов широко используется для обеспечения работы сервера. Там есть даже код для разбора флагов. Собственно, почему бы ему там не быть?

Если вам нравится фреймворк, используемый в коде, генерируемом go-swagger, то вам вполне может подойти этот код. Но если у вас на этот счёт есть свои идеи — вроде использования Gin или собственного маршрутизатора, то решения разработчиков go-swagger, отразившиеся на готовом коде, могут вас не устроить.

С помощью go-swagger можно сгенерировать и код клиента, который, как и код сервера, отличается хорошим функционалом и отражает точку зрения разработчиков go-swagger на то, каким должен быть такой код. Правда, если нужно всего лишь быстро создать такой код для целей тестирования, то, что он отражает мнение других людей, не будет выглядеть серьёзной проблемой.

После публикации этого материала мне посоветовали попробовать ещё один инструмент для генерирования кода — oapi-codegen. Код нашего сервера, созданный с помощью этого инструмента, можно найти здесь.

Я должен признать, что результаты работы oapi-codegen понравились мне гораздо больше, чем код, созданный другими опробованными мной инструментами. Это — простой и чистый код, при работе с которым легко отделить то, что сгенерировано автоматически, от того, что написано самостоятельно. Средство oapi-codegen даже понимает спецификации OpenAPI 3! Единственное, к чему я могу придраться, это то, что тут используется зависимость от пакета стороннего разработчика лишь для того, чтобы реализовать привязку параметров запроса. Лучше было бы, если бы это можно было как-то настраивать. Например — чтобы имелся бы некий параметр, позволяющий выбрать между использованием кода, входящего в состав сервера, и кода, получаемого из стороннего пакета.

Генерирование спецификаций на основе кода

Что если у вас уже имеется реализация REST-сервера, но вам очень понравилась идея его описания с помощью OpenAPI? Можно ли сгенерировать это описание на основе кода сервера?

Да — можно! Сгенерировать OpenAPI-описание сервера (правда, это снова будет описание в формате спецификации 2.0) можно с помощью специальных комментариев-аннотаций и инструментов наподобие swaggo/swag. Затем с полученным описанием можно поработать, используя различные Swagger-инструменты и, например, создать на его основе документацию.

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

Итоги?

Представьте, что у вас имеется приложение, которому необходимо работать с REST API, и при этом вам приходится выбирать между двумя сервисами.

Я с удовольствием опишу мой API в формате OpenAPI и воспользуюсь инструментом для создания документации. А вот в деле автоматического генерирования кода я буду действовать уже более осторожно. Лично я предпочитаю достаточно сильно контролировать мой серверный код. В частности, речь идёт об используемых в нём зависимостях и о его структуре. Я вижу смысл в автоматическом создании серверного кода для целей быстрого прототипирования или для каких-то экспериментов, но я не использовал бы автоматически сгенерированный серверный код как базу для собственного проекта. Конечно, я иначе бы смотрел на этот вопрос, если бы мне надо было бы еженедельно выпускать новую версию REST-сервера. В поисках баланса между использованием чужого кода и кода своего, стоит помнить о том, что преимущества от использования зависимостей обратно пропорциональны усилиям, потраченным на программный проект.

На самом деле, инструменты вроде swaggo/swag могут предложить разработчикам отличный баланс между зависимостями и собственными усилиями. Серверный код пишут с использованием самостоятельно выбранного подхода или фреймворка и оснащают его особыми комментариями, описывающими REST API. После этого соответствующий инструмент генерирует на основе этих комментариев спецификацию OpenAPI. Эту спецификацию можно использовать для создания документации к проекту или чего угодно другого, что можно создать на её основе. При таком подходе у нас появляется дополнительная полезная возможность — наличие единственного источника истины в виде комментариев. Этот источник расположен в максимальной близости к исходному коду, реализующему механизмы, описываемые в комментариях. А такой подход, кстати, всегда полезен в деле разработки программного обеспечения.

Пользуетесь ли вы спецификациями OpenAPI при создании REST-серверов?

Источник

Swagger: что это такое, и как с ним работать?

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

Ручное формирование документации — утомительное занятие. Поэтому разработчики придумали Swagger. С его помощью на основе кода можно автоматически сгенерировать спецификации API.

Что такое Swagger?

Swagger — это набор инструментов, которые помогают описывать API. Благодаря ему пользователи и машины лучше понимают возможности REST API без доступа к коду. С помощью Swagger можно быстро создать документацию и отправить ее другим разработчикам или клиентам.

В 2015 году проект Swagger сделали открытым и передали OpenAPI Initiative. Теперь сама спецификация называется OpenAPI. Swagger — инструментарий для работы с OpenAPI, название которого используется в коммерческих и некоммерческих продуктах. Если кто-то называет саму спецификацию Swagger, то это не совсем верно.

Документ спецификации OpenAPI использует YAML, но также может быть написан в формате JSON. Сам по себе он является объектом JSON.

Основные подходы

Swagger предлагает два основных подхода к генерированию документации:

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

Чтобы пользоваться вторым подходом, нужно знать синтаксис Swagger. Описания можно готовить в формате YAML/JSON. Можно упростить эту задачу, используя Swagger Editor. Конечно, второй подход позволяет сделать документацию более качественной и кастомной для каждого конкретного проекта и его особенностей, к тому же все не так сложно как может показаться, это потребует минимальных дополнительных усилий.

Swagger Core

Это Java-реализация спецификации. Для ее использования потребуется:

Для его внедрения в проект используются две зависимости. Вот примеры:

Другой способ — настроить maven-плагин. Тогда описания при сборке проекта будут генерироваться в файл YAML. Пример:

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

Swagger Codegen

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

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

Плюсы Swagger Codegen:

Чтобы добавить Swagger Codegen в проект, используйте зависимость:

Как и в случае с Swagger Core, можно настроить maven-плагин для генерации клиента или мок-сервера.

Swagger Codegen предоставляет следующие команды:

Swagger UI

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

Swagger Editor

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

Плюсы Swagger Editor:

Верхний уровень спецификации OpenAPI 3.0 содержит восемь объектов. Внутри этих верхнеуровневых объектов есть много вложенных объектов. Давайте далее последовательно рассмотрим все объекты верхнего уровня.

Первое и самое важное свойство в документации. Объект содержит информацию о спецификации OpenAPI. Пример:

В объекте info содержится основная информация об API: заголовок, описание, версия, ссылки на лицензию, обслуживание, контактные данные. Не все свойства обязательны к заполнению.

Объект содержит базовый путь, который используется в запросах через API. Под базовым путём понимается часть адреса, которая находится перед конечной точкой. Servers можно гибко настраивать, например, указывая несколько адресов для тестирования:

В этом объекте хранятся различные схемы спецификации. Схемы позволяют заметно ускорить процесс составления описаний. Например:

Теперь можно ссылаться на эту схему и при необходимости без проблем дополнять её новыми полями.

Объект для объявления того, какие механизмы безопасности можно использовать в API.

Например, требование безопасности OAuth2 :

В этом объекте можно указать дополнительную информацию. Например:

Онлайн-редактор Swagger позволяет удобно работать над документацией со спецификацией. Он предлагает разделенный интерфейс. Слева вы пишете спецификацию, а справа видите отображение Swagger UI. В него даже можно отправлять запросы, чтобы сразу проверить правильность кода.

Использование Petstore для знакомства

Авторизация

Прежде всего нужно авторизоваться. Для этого нажмите на кнопку Authorize и заполните необходимую информацию.

В примере используется модель авторизации OAuth 2.0. На самом деле, код представлен в демонстрационных целях, никакой реальной логики за авторизацией нет. Так что можно просто закрыть окно.

Создание запроса

Создадим первый запрос к API. Для этого:

Проверка результата

Напоследок выполним ещё один запрос, чтобы убедиться, что питомец создан.

В ответе должно отобразиться имя созданного ранее питомца.

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

Как выглядят сайты с документацией Swagger UI

Вот ещё несколько примеров реализации Swagger:

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

Как встроить Swagger UI в существующий сайт

Чтобы встроить Swagger UI на свой сайт:

Отображение документации можно проверить локально. Если всё в порядке, загрузите папку dist (ее можно переименовать) на сервер и добавьте документацию на существующий сайт.

Заключение

Swagger — удобный инструмент для создания документации API, который помогает разработчикам сэкономить время. Он предлагает несколько решений для интеграции в проект и формирования интерактивной версии документации, с которой будет удобно взаимодействовать другим разработчикам, внешним пользователям, клиентам.

Чтобы разобраться со Swagger дополнительно, посмотрите эти видео.

Например, вот доклад технического писателя из «Яндекса» о том, что такое вообще API и как работать со Swagger. Много времени также уделено практической части — в ней делается простой Swagger, который затем отображается в Swagger UI и в документации.

Ещё одно классное видео — подробное объяснение, как использовать Swagger:

Источник