Swagger файл что это
OpenAPI является спецификацией для описания REST API. Можно рассматривать спецификацию OpenAPI как спецификацию DITA. В DITA существуют определенные элементы XML, используемые для определения компонентов справки, а также требуемый порядок и иерархия для этих элементов. Различные инструменты могут читать DITA и создавать веб-сайт документации на основе информации.
В OpenAPI вместо XML существует набор объектов JSON с определенной схемой, которая определяет их наименование, порядок и содержимое. Этот файл JSON (часто выражается в YAML вместо JSON) описывает каждую часть API. Описывая API в стандартном формате, инструменты публикации могут программно анализировать информацию об API и отображать каждый компонент в стилизованном интерактивном виде.
Tip: Если есть желание сразу перейти к пошаговому справочнику по созданию документации в спецификации OpenAPI, см. Обзор руководства OpenAPI.
Роль технического писателя в спецификации
В большинстве проектов Тома Джонсона разработчики были не очень хорошо знакомы с Swagger или OpenAPI, поэтому он обычно создавал документ спецификации OpenAPI вручную. Кроме того, он часто не имел доступа к исходному коду, и для разработчиков английский язык был не родным. Документация была для них сложным делом.
Возможно, и нам будут попадаться инженеры, не знакомые с Swagger или OpenAPI, но заинтересованные в использовании их в качестве подхода к документации API (подход, основанный на схемах, соответствует инженерному мышлению). Таким образом, нам, вероятно, придется взять на себя инициативу, чтобы направлять инженеров к необходимой информации, подходу и другим деталям, которые соответствуют лучшим практикам для создания спецификации.
В этом отношении технические писатели играют ключевую роль в сотрудничестве с командой в разработке спецификации API. Если придерживаться философии разработки, основанной на спецификациях, эта роль (техписателя) может помочь сформировать API до его кодирования и блокировки. Это означает, что может быть возможность влиять на имена конечных точек, консистенцию и шаблоны, простоту и другие факторы, которые влияют на разработку API (на которые, обычно, не влияют технические писатели).
Swagger
Относится к инструментам API, связанным со спецификацией OpenAPI. Некоторыми из этих инструментов являются Swagger Editor, Swagger UI, Swagger Codegen, SwaggerHub и другие. Всеми инструментами управляет компания Smartbear. Для получения дополнительной информации см. Инструменты Swagger. «Swagger» являлся изначально оригинальным названием спецификации OpenAPI, но позже имя было изменено на OpenAPI, чтобы усилить открытый, не лицензионный характер стандарта. Люди иногда ссылаются на оба имени взаимозаменяемо (особенно на старых веб-страницах), но «OpenAPI» - это то, как следует обращаться к спецификации. Дополнительные сведения о разнице между OpenAPI и Swagger см. В разделе «В чем разница между Swagger и OpenAPI?».
Примеры сайтов с документаций по Swagger UI
Прежде чем мы перейдем к другому API с этим пособием по Swagger (кроме демонстрации Petstore), посмотрим на другие реализации Swagger:
Некоторые из этих сайтов выглядят одинаково, но другие, такие как The Movie Database API и Zomato, были легко интегрированы в остальную часть их сайта документации.
Глядя на примеры, можно заметить краткость документации в реализации Swagger. Эта краткость объясняется тем, что дисплей Swagger предназначен для интерактивного взаимодействия, где можно опробовать вызовы и посмотреть ответы - используя свой собственный ключ API, чтобы увидеть свои собственные данные. такой подход получил название: «учись, практикуясь». Кроме того, Swagger UI охватывает только документацию конечных точек. Концептуальные разделы обычно рассматриваются в отдельном руководстве.
Проверка спецификации
При создании спецификации OpenAPI, вместо того, чтобы работать в текстовом редакторе, можно написать свой код в редакторе Swagger. Редактор Swagger динамически проверяет контент, чтобы определить, является ли созданная спецификация валидной.
Для формата спецификации у нас есть выбор работы JSON или YAML. Пример кода выше находится в YAML. У YAML официальное определение: «YAML не является языком разметки», что означает, что в YAML нет тегов разметки <> , как в других языках разметки, таких как XML.
YAML зависим от пробелов и двоеточий, устанавливающих синтаксис объекта. Такое пространственно-чувствительное форматирование делает код более понятным для человека. Однако, иногда могут возникнуть сложности с расстановкой правильных интервалов.
Создание запроса
Теперь создадим запрос:
После того, как мы нажмем кнопку Try it out , значение примера в поле «Тело запроса» станет редактируемым.
- В поле «Example Value» изменяем первое значение id на случайное целое число, например 193844 . Также значение второго name на другое (имя вашего питомца).
- Нажимаем Execute .
Пользовательский интерфейс Swagger отправляет запрос и показывает отправленный curl. Раздел Ответы показывает ответ. (Если выбрать JSON вместо XML в раскрывающемся списке «Response content type», формат ответа будет показан в формате JSON.)
Important: Petstore - это функционирующий API, и вы фактически создали питомца. Теперь вам нужно взять на себя ответственность за вашего питомца и начать кормить и ухаживать за ним! Шутки - шутками, но большинство пользователей не осознают, что играют с реальными данными, когда выполняют ответы в API (особенно при использовании своего собственного ключа API). Эти тестовые данные могут быть чем-то, что вам придется стереть при переходе от исследований и изучения API к использованию API для реального использования.
Обзор Swagger UI
Swagger UI - один из самых популярных инструментов для создания интерактивной документации. Swagger UI создает интерактивную консоль API для экспериментов с запросами в реальном времени. Кроме того, Swagger UI (активно управляемый проект с лицензией Apache 2.0) поддерживает последнюю версию спецификации OpenAPI (3.x) и интегрируется с другими инструментами Swagger.
Прежде чем мы углубимся в Swagger, нужно прояснить ключевые термины.
Swagger UI
Swagger UI - позволяет визуализировать ресурсы API и взаимодействовать с ними без какой-либо логики реализации. Он автоматически генерируется из вашей спецификации OpenAPI (ранее известной как Swagger), а визуальная документация упрощает внутреннюю реализацию и использование на стороне клиента.
Вот пример Swagger UI который визуализирует документацию для моего pet-project:
Нажавши на кнопку "Try it out", мы можем выполнить запрос за сервер и получить ответ от него:
Swagger
Документацию должно быть легко читать, писать, парсить, генерировать, исправлять, обновлять и прочее. Решение должно быть настолько простым, чтобы даже самые ленивые разработчики им пользовались. После небольшого исследования мы в Ataccama решили использовать Swagger для документирования наших REST APIs.
Swagger — это фреймворк и спецификация для определения REST APIs в формате, дружественном к пользователю и компьютеру (в нашем случае JSON или YAML). Но Swagger — это не просто спецификация. Основная его мощь заключается в дополнительных инструментах. Для Swagger существует огромное количество бесплатных утилит (как официальных, так и написанных сообществом), которые могут сделать жизнь (вашу и ваших коллег) немного более счастливой. Вы можете установить все это на свои собственные сервера и посмотреть, как это работает — например, попробовать работу с браузером документов или Swagger онлайн-редактором.
Swagger Codegen
Генерирует код SDK для множества различных платформ (таких как Java, JavaScript, Scala, Python, PHP, Ruby, Scala и другие). Код SDK помогает разработчикам интегрировать API на конкретной платформе и обеспечивает более надежные реализации, которые могут включать в себя больше масштабирования, многопоточности и т.д.. В общем, SDK - это наборы инструментов для реализации запросов, сделанных с помощью API. Swagger Codegen генерирует клиентские SDK практически на каждом языке программирования. См. Swagger Codegen для получения дополнительной информации. Смотрите также SDK и примеры приложений.
Хорошо, так что же есть такое Swagger и в чем его полезность миру?
По сути Swagger – это фреймворк для спецификации RESTful API. Его прелесть заключается в том, что он дает возможность не только интерактивно просматривать спецификацию, но и отправлять запросы – так называемый Swagger UI, вот так это выглядит:
Недостатки OpenAPI и Swagger UI
Несмотря на то, что Swagger обладает интерактивными возможностями апеллировать к желаниям пользователей «дай мне попробовать», у Swagger и OpenAPI есть некоторые недостатки:
- Информация только о ссылке: Во-первых, спецификация OpenAPI и выходные данные Swagger UI охватывают только документацию ссылки. OpenAPI предоставляет основу каждой конечной точки: описание, параметры, пример запроса и ответа. OpenAPI не содержит места для описания начала работы, информации о том, как получить ключи API, как запустить пример приложения, информацию об ограничениях скорости или о сотне других деталей, которые находятся в гайдах для разработчиков. Поэтому, несмотря на то, что есть этот крутой интерактивный инструмент, позволяющий пользователям исследовать и изучать наш API, мы все равно должны предоставить руководство пользователя. По аналогии, вывод Javadoc или Doxygen для основанной на библиотеке API не научит пользователей, как на самом деле использовать наш API. Нам все еще нужно описать сценарии использования класса или метода, объяснить, как настроить код, что делать с ответом, как устранить неполадки и т.д. Короче говоря, писать реальные справочные и пошаговые руководства.
- Избыточность / дублирование информации: В OpenAPI потенциально есть два места, где описываются конечные точки и параметры (описание ссылки Swagger UI и руководство пользователя), и нужно либо синхронизировать их, встроить одно в другое, или иным образом указать связь между ними. Подробнее разберемся в разделе Интеграция Swagger с собственной документацией.
- Сложность рабочего процесса API: Сложность API также может создать ограничение в Swagger. Питер Грюнбаум, опубликовавший несколько учебных пособий по документированию API для Udemy, говорит, что автоматизированные инструменты, такие как Swagger, работают лучше всего для простых API. Если есть конечные точки, которые имеют сложные взаимозависимости и требуют специальных рабочих процессов настройки или другой не интуитивной обработки, простой характер пробного интерфейса Swagger может, вероятно, заставить пользователей почесать голову. Например, если нужно сначала настроить службу API, прежде чем конечная точка что-либо возвратит, а затем использовать одну конечную точку, чтобы получить определенный объект, который передается в параметры другой конечной точки, и т.д., функции Try-it-out в Swagger UI не будет иметь большого смысла для пользователей без подробного руководства.
- Запросы к реальным данным: Некоторые пользователи могут не осознавать, что нажатие кнопки Try-it-out создает реальные вызовы для их собственных учетных записей на основе используемых ими ключей API. Смешивание использования исследовательской изолированной программной среды, такой как Swagger, с реальными данными может впоследствии создать головные боли, когда пользователи начнут спрашивать, как можно удалить все тестовые данные или почему их фактические данные теперь испорчены. Для этих сценариев лучше всего настроить песочницу или тестовую учетную запись для пользователей. Но это легче сказать, чем сделать. Можно обнаружить, что компания не предоставляет «песочницу» для тестирования API. Все вызовы API выполняются только для реальных данных.
- Ограничения CORS: Можно столкнуться с ограничениями CORS (Cross-Origin Resource Sharing - обмен ресурсами между источниками) при выполнении вызовов API. Не все API принимают запросы, выполненные с веб-страницы. Если вызовы не выполняются, нужно открыть консоль JavaScript и проверить, не блокирует ли CORS запрос. Если это так, нужно попросить разработчиков внести коррективы, чтобы учесть запросы, инициированные из JavaScript на веб-страницах. См. CORS Support для более подробной информации.
- Проблематика обширных параметров тела запроса: конечные точки с длинными параметрами тела запроса, как правило, проблематичны. Один API может включать запросы с параметрами тела запроса длиной в сотни строк (тело запроса использовалось для настройки сервера API). С таким параметром тела запроса отображение пользовательского интерфейса Swagger оказалось непригодным для использования. Команда вернулась к гораздо более примитивным подходам (таким как таблицы) для перечисления всех параметров и их описания.
Swagger Core
Swagger Code - это Java-реализация спецификации OpenAPI
Для того что бы использовать Swagger Core во все орудие, требуется:
Java 8 или больше
Apache Maven 3.0.3 или больше
Jackson 2.4.5 или больше
Что бы внедрить его в проект, достаточно добавить две зависимости:
Также можно настроить maven плагин, что бы наша документация при сборке проект генерировалсь в YAML
Дальше нам необходимо добавить конфиг в проект.
Для конфигурации Swagger необходимо добавить два бина. Где нам нужно будет описать название приложения, версию нашего API, так же можно добавить контакт разработчик который отвечает за данные API
После добавление нужных нам зависимостей, у нас появятся новые аннотация с помощью которых можно документировать наш код.
Вот некоторые из них:
@Parameter - Представляет один параметр в операции OpenAPI.
@RequestBody - Представляет тело запроса в операции
@ApiResponse - Представляет ответ в операции
@Tag - Представляет теги для операции или определения OpenAPI.
@Server - Представляет серверы для операции или для определения OpenAPI.
@Callback - Описывает набор запросов
@Link - Представляет возможную ссылку времени разработки для ответа.
@Schema - Позволяет определять входные и выходные данные.
@ArraySchema - Позволяет определять входные и выходные данные для типов массивов.
@Content - Предоставляет схему и примеры для определенного типа мультимедиа.
@Hidden - Скрывает ресурс, операцию или свойство
Некоторые утешения
Несмотря на недостатки спецификации OpenAPI, он все же настоятельно рекомендуется ее для описания API. OpenAPI быстро становится средством для все большего и большего количества инструментов (от кнопки запуска Postman для почти каждой платформы API), для быстрого получения информации о нашем API и для превращения ее в доступную и интерактивную документацию. С помощью своей спецификации OpenAPI можно портировать свой API на многие платформы и системы, а также автоматически настраивать модульное тестирование и создание прототипов.
Swagger UI обеспечивает определенно хорошую визуальную форму для API. Можно легко увидеть все конечные точки и их параметры (например, краткий справочник). Основываясь на этой структуре, можно помочь пользователям понять основы вашего API.
Кроме того, изучение спецификации OpenAPI и описание своего API с его объектами и свойствами поможет расширить свой собственный словарь API. Например, станет понятно, что существует четыре основных типа параметров: параметры «пути», параметры «заголовка», параметры «запроса» и параметры «тела запроса». Типы данных параметров в REST: «Boolean», «number», «integer» или «string». В ответах содержатся «objects», содержащие «strings» или «arrays».
Короче говоря, реализация спецификации даст еще и представление о терминологии API, которая, в свою очередь, поможет описать различные компоненты своего API достоверными способами.
OpenAPI может не подходить для каждого API, но если API имеет довольно простые параметры, без большого количества взаимозависимостей между конечными точками, и если нет проблем исследовать API с данными пользователя, OpenAPI и Swagger UI могут быть мощным дополнением к документации. Можно давать пользователям возможность опробовать запросы и ответы.
С таким интерактивным элементом документация становится больше, чем просто информация. С помощью OpenAPI и Swagger UI мы создаем пространство для пользователей, которые одновременно могут читать нашу документацию и экспериментировать с нашим API. Эта комбинация имеет тенденцию предоставлять мощный опыт обучения для пользователей.
И как это работает?
Идея в конфигурации отображения с помощью специальных аннотаций у методов 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:
Прочая информация, в частности инструкция по использованию, представлена здесь:
Общая информация
Визуализация спецификации OpenAPI с помощью Swagger UI
После того, как получился действующий документ по спецификации OpenAPI, описывающий API, можно “скормить” эту спецификацию различным инструментам, чтобы проанализировать ее и сгенерировать интерактивную документацию, аналогичную примеру Petstore.
Наиболее распространенным инструментом, используемым для анализа спецификации OpenAPI, является Swagger UI. (Помните, что «Swagger» относится к инструментам API, тогда как «OpenAPI» относится к независимой от поставщика спецификации, не зависящей от инструмента.) После загрузки пользовательского интерфейса Swagger его довольно легко настроить с помощью собственного файла спецификации. Руководство по настройке Swagger UI есть в этом разделе.
Код пользовательского интерфейса Swagger генерирует экран, который выглядит следующим образом:
На изображении видно, как Swagger отображает спецификацию Open API
Можно ознакомиться с примером интеграции Swagger UI с примером API сервиса погоды, использованным в качестве примера курса.
Некоторые дизайнеры критикуют выпадающие списки Swagger UI как устаревшие. В то же время разработчики считают одностраничную модель привлекательной и способной уменьшать или увеличивать детали. Объединяя все конечные точки на одной странице в одном представлении, пользователи могут сразу увидеть весь API. Такое отображение дает пользователям представление в целом, что помогает уменьшить сложность и позволяет им начать. Во многих отношениях отображение Swagger UI является кратким справочным руководством по API.
Swagger Editor
Swagger Editor - позволяет редактировать спецификации Swagger API в YAML внутри вашего браузера и просматривать документацию в режиме реального времени. Затем можно сгенерировать допустимые описания Swagger JSON и использовать их с полным набором инструментов Swagger (генерация кода, документация и т. Д.).
На верхнем уровне в спецификации OpenAPI 3.0 существует восемь объектов. Внутри этих верхнеуровневых объектов есть много вложенных объектов, но на верхнем уровне есть только следующие объекты:
Для работы над документацией со спецификацией используется онлайн-редактор Swagger Редактор Swagger имеет разделенное представление: слева пишем код спецификации, а справа видим полнофункциональный дисплей Swagger UI. Можно даже отправлять запросы из интерфейса Swagger в этом редакторе.
Редактор Swagger проверит контент в режиме реального времени, и укажет ошибки валидации, во время кодирования документа спецификации. Не стоит беспокоиться об ошибках, если отсутствуют X-метки в коде, над которым идет работа.
Первым и важным свойством для документации это openapi. В объекте указывается версия спецификации OpenAPI. Для Swagger спецификации это свойство будет swagger:
Объект info содержит основную информацию о вашем API,включая заголовок, описание, версию, ссылку на лицензию, ссылку на обслуживания и контактную информацию. Многие из этих свойство являются не обязательными.
Объект servers указывает базовый путь, используемый в ваших запросах API. Базовый путь - это часть URL, которая находится перед конечной точкой. Объект servers обладает гибкой настройкой. Можно указать несколько URL-адресов:
paths - Это та же “конечная точка” в соответствии с терминологии спецификации OpenAPI. Каждый объект path содержит объект operations - это методы GET, POST, PUT, DELETE:
Объект components уникален среди других объектов в спецификации OpenAPI. В components хранятся переиспользуемые определения, которые могут появляться в нескольких местах в документе спецификации. В нашем сценарии документации API мы будем хранить детали для объектов parameters и responses в объекте components
Постой, как так получается, что продукт успешно функционирует уже давно, а API вы к нему пишете только сейчас?
Все верно, как такового удобного публичного API у E до недавнего времени не существовало. Фактически вся работа происходила через web-интерфейс, а back-end состоял из множества внутренних микросервисов, с которыми невозможно было интегрироваться извне без четкого понимания внутренней бизнес-логики, уж не говоря о том, что сами они на значительную долю состояли из легаси. Нужно было обратить внимание на клиентов, которые хотят непосредственно напрямую взаимодействовать с сервером, а значит предоставить им красивое и удобное API. Что для этого потребуется? Все, о чем было написано чуть раньше – самим взять и наладить работу со всеми внутренними микросервисами, а также обеспечить удобную и красивую документацию, сделав это красиво, понятно, и самое главное – коммерчески успешно.
Вступление
Несколько месяцев назад один из наших бекенд разработчиков интернов получил задачу — разработать новый простой сервис. Сервис должен был генерировать емайл отчеты о пользовательской активности. В задаче не было ничего сложного и у интерна все получилось. Однако через несколько недель мы захотели включить в отчет более детальную информацию о некоторых конкретных пользователях. Я решил обновить этот сервис самостоятельно. “Просто получи данные из нашего пользовательского сервиса и вставь их в емайл”, — думал тогда я.
На это у меня ушло несколько часов, и даже пришлось подключить двоих других разработчиков только для того, чтобы найти правильные REST endpoints и необходимые мен структуры. “Никогда больше. Должен быть более правильный метод это сделать…”, — крутилось у меня в голове все это время.
Авторизация запроса
Прежде чем делать какие-либо запросы, нужна авторизация. Нажимаем кнопку Authorize и заполняем информацию, требуемую в окне «Авторизация», изображенном ниже:
Пример Petstore имеет модель безопасности OAuth 2.0. Код авторизации только для демонстрационных целей. Нет никакой реальной логики авторизации этих запросов, поэтому просто закрываем окно Авторизации.
Взгляд на спецификацию OpenAPI
Чтобы лучше понять спецификацию OpenAPI, давайте взглянем на некоторые выдержки из спецификации. Углубимся в каждый элемент в следующих разделах.
Официальное описание спецификации OpenAPI доступно в репозитории Github. Элементы OpenAPI - это paths , parameters , responses и security . Каждый из этих элементов является объектом JSON, который содержит свойства и массивы.
В спецификации OpenAPI ваши конечные точки это paths . Конечная точка /pet , в спецификации OpenAPI может выглядеть следующим образом:
Это формат YAML, взят из Swagger PetStore
Вот что значат объекты в этом коде:
Note: Может потребоваться некоторое время, чтобы понять спецификацию OpenAPI. Возьмем пару недель и несколько примеров спецификации, чтобы посмотреть, особенно в контексте фактического API. Спецификация OpenAPI достаточно общая, чтобы описать почти каждый API REST, поэтому некоторые части могут быть более применимыми, чем другие.
Ресурсы для дальнейшего чтения
Вот источники для получения дополнительной информации об OpenAPI и Swagger:
Conclusions
Документация стала более понятней для бизнес юзера так и для техническим юзерам (Swagger UI, Open Specifiation)
Можно проверять насколько совместимы изменения. Можно настраивать это в дженкинсе
Нет ни какой лишней документации к коде, код отдельно, документация отдельно
Оригинальная статья является размышления на тему почему документация в мире микросервисов критично необходима и как ее можно создавать и публиковать используя swagger. Пошаговой инструкцией по настройке она точно не является.
👨💻 Практическое занятие: Создание спецификации OpenAPI в Swagger UI
На этом занятии мы создадим документацию в Swagger UI в спецификации OpenAPI. Если вы используете один из предварительно созданных файлов OpenAPI, вы можете увидеть демонстрацию того, что мы создадим здесь: OpenWeatherMap Swagger UI или Sunrise/sunset Swagger UI).
Для интеграции спецификации OpenAPI в Swagger UI:
- Подготавливаем действительный документ спецификации OpenAPI:
- Инструкции по созданию документа спецификации OpenAPI с нуля см. В обзоре руководства по OpenAPI.
- Для использования предварительно созданного документа в спецификации OpenAPI, можно использовать файл спецификации OpenWeatherMap или файл спецификации Sunrise/sunset API (Клик правой кнопкой мыши ссылку и сохраните файл YAML на рабочем столе.)
Единственная папка, с которой мы будем работать в загруженном zip-архиве, - это папка dist (сокращение от дистрибутива). Все остальное используется, только если мы перекомпилируем файлы Swagger, что выходит за рамки этого руководства.
-
Извлечем папку dist из папки swagger-ui-master в другой каталог. (После этого папку swagger-ui-master и zip-файл можно удалить.)
Перетащим файл спецификации OpenAPI (из шага 1) в папку dist. (Если вы используете предварительно созданные файлы OpenAPI, файл называется либо openapi_openweathermap.yml, либо openapi_sunrise_sunset.yml.) Ваша файловая структура должна выглядеть следующим образом:
Кастомизация Swagger UI
Swagger UI можно настроить по своему, чтобы вывод информации не выглядел однообразно: можно настроить цвета интерфейса Swagger, добавить собственный логотип, добавить других пользовательских стилей. Можно интегрировать Bootstrap, чтобы получить модальные окна, где пользователи могут генерировать свои коды авторизации. Можно даже добавить функции сворачивания/разворачивания в элементе description , чтобы предоставить больше информации пользователям.
Однако, помимо этих простых модификаций, потребуется немного мастерства веб-разработчика, чтобы существенно изменить отображение пользовательского интерфейса Swagger. Возможно, понадобятся навыки веб-разработки.
Как мы это делаем?
Если вы тоже думаете, что Swagger — это здорово, то читайте дальше. Сейчас будет немного подробностей о том, как мы используем его в Ataccama, в таинственном мире микросервисов.
У каждого микросервиса в определенной папке лежит файл со Swagger описанием и хранится это все прямо в git-репозитории. Описания могут быть как сгенерированы при помощи Swagger generator, так и записаны туда вручную. Прелесть заключается в том, что для записи определений используются JSON и YAML форматы. Их легко распарсить, и во время сборки проекта мы можем автоматически проверять соответствие REST endpoints и документации. Несоответствия будут генерировать предупреждения, и тем самым стимулировать разработчика поддерживать документацию в актуальном состоянии.
Хранение документации внутри микросервиса позволяет нам отображать её в любое время прямо из этого микросервиса в процессе работы. Это помогает тестировать и отлаживать REST endpoints в процессе развертывания сервиса на собственной машине. А ещё у Swagger есть инструмент с веб интерфейсом для тестирования REST endpoints.
Поскольку каждый микросервис предоставляет собственную документацию, мы можем настроить специальную задачу для Дженкинса (или любого другого CI сервера), которая сгенерирует полную документацию для всего проекта. Эта задача собирает Swagger файлы из всех микросервисов, производит некоторые минимальные модификации (дедупликация, удаление ненужных атрибутов) и на выходе генерирует единый Swagger файл, содержащий полную актуальную информацию для всего проекта.
Знакомство со Swagger при помощи Petstore
Чтобы лучше понять интерфейс Swagger, давайте рассмотрим пример Swagger Petstore. В примере Petstore сайт генерируется с помощью Swagger UI.
Конечные точки сгруппированы следующим образом:
Публикация документации.
Централизованное хранение и редактирование документации — это только первый шаг. Следующий — сделать ее доступной для всех разработчиков, тестеров и остальных заинтересованных людей в компании. И Swagger UI — это именно то, что вам для этого понадобится. При помощи небольшой JavaScript библиотеки Swagger UI генерирует HTML элементы для всех ваших REST endpoints, которые далее можно упорядочивать с помощью HTML разметки.
По умолчанию Swagger UI подгружает собственный Swagger файл с примерами. Все остальные API должны быть загружены вручную. Но конфигурация занимает всего несколько секунд.Кроме того, использование докера дает нам еще несколько преимуществ:
Каждый разработчик может просто загрузить документацию и запустить её на собственном компьютере всего одной командой.
Подход: разработка по спецификации
Можно сгенерировать свою спецификацию из аннотаций кода, но говорят, что автоматическая генерация - не лучший подход. Майкл Стоу (Michael Stowe) в статье Беспрепятственный REST: руководство по проектированию Perfect API рекомендует группам вручную реализовать спецификацию, а затем обрабатывать документ спецификации как документ, который разработчики используют при выполнении реального кодирования. Этот подход часто упоминается как «spec-first development».
Spec-first development это философия о том, как разрабатывать API более эффективно. Если вы следуете философии «сначала спецификация», вы сначала пишете спецификацию и используете ее в качестве контракта, к которому разработчики пишут код.
Другими словами, разработчики обращаются к спецификации, чтобы увидеть, как должны называться имена параметров, каковы должны быть ответы и так далее. После того, как этот «контракт» или «план» был принят, Стоу говорит, можно поместить аннотации в свой код (при желании), чтобы сгенерировать документ спецификации более автоматизированным способом. Но не стоит кодировать без предварительной спецификации.
Компания Smartbear, которая делает SwaggerHub (платформу для совместной работы команд над спецификациями API Swagger), говорит, что теперь для команд чаще встречается ручное написание спецификации, а не встраивание аннотаций исходного кода в программный код для автоматической генерации. Подход “spec-first development” в первую очередь помогает работать документации среди большего количества членов команды, нежели только инженеров. Определение спецификации перед кодированием также помогает командам создавать лучшие API.
Даже до создания API спецификация может генерировать ложный ответ, добавляя определения ответа в спецификацию. Мок-сервер генерирует ответ, который выглядит так, как будто он исходит от реального сервера, но это просто предопределенный ответ в коде, и кажется динамичным для пользователя.
Другие инструменты визуализации
Помимо Swagger UI есть и другие инструменты, которые могут анализировать нашу документацию OpenAPI. Вот список из нескольких инструментов: Restlet Studio, Apiary, Apigee, Lucybot, Gelato, Readme.io, swagger2postman, отзывчивую тему swagger-ui, Postman Run Buttons и многое другое.
Swagger Tools
Swagger или OpenAPI framework состоит из 4 основных компонентов:
Swagger Core - позволяет генерировать документацию на основе существующего кода основываясь на Java Annotation.
Swagger Codegen - позволит генерировать клиентов для существующей документации.
Swagger UI - красивый интерфейс, который представляет документацию. Дает возможность просмотреть какие типы запросов есть, описание моделей и их типов данных.
Swagger Editor - Позволяет писать документацию в YAML или JSON формата.
Теперь давайте поговорим о каждом компоненте отдельно.
Введение
Я на 99% уверен у многих из вас были проблемы с поиском документации для нужного вам контроллера. Многие если и находили ее быстро, но в конечном итоге оказывалось что она работает не так как описано в документации, либо вообще его уже нет.
Сегодня я вам докажу, что есть способы поддерживать документацию в актуальном виде и в этом мне будет помогать Open Source framework от компании SmartBear под названием Swagger, а с 2016 года он получил новое обновление и стал называться OpenAPI Specification.Swagger - это фреймворк для спецификации RESTful API. Его прелесть заключается в том, что он дает возможность не только интерактивно просматривать спецификацию, но и отправлять запросы – так называемый Swagger UI.
Также возможно сгенерировать непосредственно клиента или сервер по спецификации API Swagger, для этого понадобится Swagger Codegen.
Swagger UI
Веб-фрэймворк (на GitHub), который анализирует документ в спецификации OpenAPI и создает веб-страницу интерактивной документации. Swagger UI - это инструмент, который превращает спецификацию в подобный Petstore-сайт.
Swagger Codegen
Swagger Codegen - это проект, который позволяет автоматически создавать клиентские библиотеки API (создание SDK), заглушки сервера и документацию с учетом спецификации OpenAPI.
В настоящее время поддерживаются следующие языки / фреймворки:
Node.js (ES5, ES6, AngularJS with Google Closure Compiler annotations)
C++ (cpprest, Qt5, Tizen)
Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy, Play Framework, PKMST)
C++ (Pistache, Restbed)
Ruby (Sinatra, Rails5)
API documentation generators:
Что бы внедрить его в проект, достаточно добавить зависимость, если используете Swagger:
и если используете OpenApi 3.0, то:
Можно настроить maven плагин, и уже на процессе сборки мы можем сгенерировать нужный для нас клиент либо мок сервиса.
Также все это можно выполнить с помощью командной строки.
Запустив джарник codegen и задав команду help можно увидеть команды, которые предоставляет нам Swagger Codegen:
config-help - Справка по настройке для выбранного языка
generate - Сгенерировать код с указанным генератором
help - Отображение справочной информации об openapi-generator
list - Перечисляет доступные генераторы
meta - Генератор для создания нового набора шаблонов и конфигурации для Codegen. Вывод будет основан на указанном вами языке и будет включать шаблоны по умолчанию.
validate - Проверить спецификацию
version - Показать информацию о версии, используемую в инструментах
Для нас самые нужные команды это validate, которая быстро проверять на валидность спецификации и generate, с помощью которой мы можем сгенерировать Client на языке Java
java -jar openapi-generator-cli-4.3.1.jar validate -i openapi.yaml
java -jar openapi-generator-cli-4.3.1.jar generate -i openapi.yaml -g java --library jersey2 -o client-gener-new
OpenAPI
Swagger Editor
Онлайн-редактор, который проверяет документацию OpenAPI на соответствие правилам спецификации OpenAPI. Редактор Swagger помечает ошибки и дает советы по форматированию.
Автоматическая генерация файла OpenAPI из аннотаций кода
Вместо того, чтобы кодировать документ в спецификации OpenAPI вручную, также можно автоматически сгенерировать его из аннотаций в программном коде. Этот подход, ориентированный на разработчиков, имеет смысл, если есть большое количество API-интерфейсов или если для технических писателей нецелесообразно создавать эту документацию.
Swagger предлагает множество библиотек, которые можно добавлять в свой программный код для создания документа в спецификации. Эти библиотеки Swagger анализируют аннотации, которые добавляют разработчики, и генерируют документ в спецификации OpenAPI. Эти библиотеки считаются частью проекта Swagger Codegen. Методы аннотации различаются в зависимости от языка программирования. Например, вот справочник по аннотированию кода с помощью Swagger для Scalatra. Для получения дополнительной информации о Codegen см. Сравнение инструментов автоматического генерирования кода API для Swagger по API Evangelist. Дополнительные инструменты и библиотеки см. В разделах «Интеграции и инструменты Swagger» и «Интеграция с открытым исходным кодом».
Хотя этот подход и «автоматизирует» генерацию спецификации, нужно еще понимать, какие аннотации добавить и как их добавить (этот процесс не слишком отличается от комментариев и аннотаций Javadoc). Затем нужно написать контент для каждого из значений аннотации (описывая конечную точку, параметры и т. Д.).
Короче говоря, поработать все нужно - автоматизированная часть заставляет библиотеки Codegen генерировать определения модели и действительный документ, который соответствует схеме OpenAPI. Тем не менее, многие разработчики взволнованы этим подходом, потому что он предлагает способ генерировать документацию из аннотаций кода, что разработчики годами делали с другими языками программирования, такими как Java (используя Javadoc) или C ++ (используя Doxygen). Они обычно считают, что генерация документации из кода приводит к меньшему отклонению документации. Документы, будут оставаться актуальными, если будут тесно связан с кодом.
Если идти по этому пути, нужно убедиться, что есть доступ к исходному коду для внесения изменений в аннотации. В противном случае разработчики будут писать документацию (что может и хорошо, но часто приводит к плохим результатам).
Проверка создания питомца
👨💻 Практическое занятие: Исследуем API PetStore в Swagger UI
Давайте познакомимся с пользовательским интерфейсом Swagger, используя Petstore.
Как и в большинстве основанных на Swagger’е инструментов, в интерфейсе Swagger есть кнопка «Try it out». Для работы необходима авторизация в Swagger. Авторизация по нажатии на кнопку Authorize , в появившемся окне нужно вставить корректную информацию. При желании авторизоваться можно добавив любой номер в поле api_key и нажав Authorize . Окно авторизации Petstore предназначено только для демонстрации, так что окно можно просто закрыть.
Разворачиваем конечную точку Pet
Нажимаем на кнопку Try it out . После нажатие пример значения в поле “Тело запроса” станет редактируемым.
В примере заменяем значение id на другое целое (не повторяющееся) число. Далее меняем значение value на какое-нибудь узнаваемое (имя щенка - Puppy ).
Swagger UI отправляет запрос и показывает отправленный curl. В примере был отправлен curl:
Обратите внимание, что с параметром -d (data) параметр тела запроса экранируется и добавляется непосредственно в команду curl, а не загружается из файла (как описано в Общих командах curl, связанных с REST).
В разделе “Ответы” Swagger UI выдает ответ сервера. По умолчанию ответ возвращает XML:
Если выбрать в выпадающем списке “Response content type” JSON, то в ответе вернется JSON вместо XML.
“Petstore” - является действующим API, питомец фактически создан. Для забавы развернем конечную точку GET / pet / , нажимаем Try it out , вводим id питомца, который использовали в предыдущей операции, а затем выполняем запрос. В ответе видим имя питомца, которое совпадает с тем, что ввели в предыдущем примере.
Основные подходы
Swagger имеет два подхода к написанию документации:
Документация пишется на основании вашего кода.
Данный подход позиционируется как "очень просто". Нам достаточно добавить несколько зависимостей в проект, добавить конфигурацию и уже мы будем иметь нужную документацию, хоть и не настолько описанной какою мы хотели.
Код проекта становиться не очень читабельным от обилия аннотаций и описания в них.
Вся документация будет вписана в нашем коде (все контроллеры и модели превращаются в некий Java Swagger Code)
Подход не советуют использовать, если есть возможности, но его очень просто интегрировать.
Документация пишется отдельно от кода.
Данный подход требует знать синтаксис Swagger Specification.
Документация пишется либо в YAML/JSON файле, либо в редакторе Swagger Editor.
Заключение
Это был краткий наглядный обзор для начинающих разработчиков API, целью которого было предоставить общую картину того, что такое Swagger, зачем он нужен и какие он дает основные плюсы с моей личной точки зрения.Всем привет. Это мой первый пост на Хабре и я хочу поделиться с вами своим опытом в исследовании нового для себя фреймворка.
Мне предоставился момент выбрать тему и подготовить презентацию для своей команды. Вдохновившись спикером Евгений Маренковым, я решил выбрать данную тему. В процессе подготовки, я облазил много статей и репозиториев, чтобы компактно и эффективно донести нужную информацию.
Сейчас хочу поделиться ею в надежде, что кому-то она поможет в изучение Swagger (OpenApi 3.0)
И это только начало.
Автор Lubos Palisek
Backend software developer in Ataccama. Greedy for new cloud based technologies and ideas.Ataccama Corporation – международная компания, производитель программного обеспечения, специализирующаяся в области решений по управлению качеством данных, управлению мастер-данными и управления данными предприятия (data governance), решениями которого уже воспользовались более 250 компаний, начиная от предприятий среднего размера и заканчивая международными компаниями из различных отраслей.
Swagger UI предоставляет Фреймворк, который читает спецификацию OpenAPI. и создает веб-страницу с интерактивной документацией. В этом руководстве показано, как интегрировать документ спецификации OpenAPI в интерфейс Swagger.
Концептуальный обзор OpenAPI и Swagger можно посмотреть в разделе Знакомство со спецификациями OpenAPI и Swagger. Пошаговое руководство по созданию документа спецификации OpenAPI смотрим в Обзоре руководства OpenAPI 3.0.
Читайте также: