Пользовательский интерфейс Swagger предоставляет платформу, которая считывает спецификацию OpenAPI. и создает веб-сайт с интерактивной документацией. В этом руководстве показано, как интегрировать документ спецификации OpenAPI с пользовательским интерфейсом Swagger.
Концептуальный обзор OpenAPI и Swagger см. в разделе Общие сведения о спецификациях OpenAPI и Swagger. Пошаговое руководство по созданию документа спецификации OpenAPI см. в главе «Обзор руководства по OpenAPI 3.0».
Обзор Swagger UI
Swagger UI — один из самых популярных инструментов интерактивной документации. Пользовательский интерфейс Swagger создает интерактивную консоль API для экспериментов с запросами в реальном времени. Кроме того, пользовательский интерфейс Swagger (активно управляемый проект с лицензией Apache 2.0) поддерживает последнюю версию спецификации OpenAPI (3.x) и интегрируется с другими инструментами Swagger.
Прежде чем мы углубимся в Swagger, необходимо прояснить ключевые понятия.
Swagger
Относится к инструментам API, связанным со спецификацией OpenAPI. Некоторые из этих инструментов — редактор Swagger, пользовательский интерфейс Swagger, Swagger Codegen, SwaggerHub и другие. Все инструменты управляются Smartbear. Дополнительные сведения см. в документе Swagger Tools. Инструменты чванства. «Swagger» было первоначальным названием спецификации OpenAPI, но позже название было изменено на OpenAPI, чтобы усилить открытый, нелицензионный характер стандарта. Люди иногда называют оба имени взаимозаменяемо (особенно на старых веб-сайтах), но «OpenAPI» — это то, как следует ссылаться на спецификации. Дополнительные сведения о различиях между OpenAPI и Swagger см. в разделе «В чем разница между Swagger и OpenAPI?»
OpenAPI
Официальное название спецификации OpenAPI. Спецификация OpenAPI предоставляет набор свойств, которые можно использовать для описания REST API. Работающий действительный документ можно использовать для создания интерактивной документации, создания клиентских SDK, запуска модульных тестов и многого другого. Подробности спецификации можно найти на GitHub по адресу https://github.com/OAI/OpenAPI-Specification. В рамках инициативы Linux Foundation Open API спецификация OpenAPI должна быть независимой от поставщика (в ее разработке участвуют многие компании).
Swagger Editor
Онлайн-редактор, проверяющий документацию OpenAPI на соответствие правилам, содержащимся в спецификации OpenAPI. Редактор Swagger помечает ошибки и дает советы по форматированию.
Swagger UI
Веб-фреймворк (на GitHub), который анализирует документ спецификации OpenAPI и создает интерактивный веб-сайт документации. Пользовательский интерфейс Swagger — это инструмент, который превращает спецификации в веб-сайт, похожий на Petstore.
Swagger Codegen
Генерирует код SDK для множества различных платформ (таких как Java, JavaScript, Scala, Python, PHP, Ruby и другие). Код SDK помогает разработчикам интегрировать API на определенную платформу и обеспечивает более надежные реализации, которые могут включать большую масштабируемость, многопоточность и т. д. Как правило, SDK представляют собой наборы инструментов для реализации запросов, сделанных с использованием API. Swagger Codegen создает клиентский SDK практически на любом языке программирования. Дополнительные сведения см. в разделе Swagger Codegen. См. также SDK и примеры приложений.
Знакомство со Swagger при помощи Petstore
Чтобы лучше понять интерфейс Swagger, давайте рассмотрим пример Swagger Petstore. В примере с Petstore страница создается с использованием пользовательского интерфейса Swagger.
Конечные точки сгруппированы следующим образом:
Авторизация запроса
Перед отправкой любых запросов требуется авторизация. Нажмите кнопку «Авторизовать» и введите необходимую информацию в окно «Авторизация», показанное ниже:
В примере Petstore используется модель безопасности OAuth 2.0. Код авторизации предназначен только для демонстрационных целей. Нет реальной логики для авторизации этих запросов, поэтому просто закройте окно авторизации.
Создание запроса
Теперь составим запрос:
Когда вы нажимаете «Попробовать», образец значения в поле «Тело запроса» становится редактируемым.
- В поле «Пример значения» измените первое значение идентификатора на случайное целое число, например 193844. Также измените значение отчества на другое (имя вашего питомца).
- Нажмите «Выполнить».
Пользовательский интерфейс Swagger делает запрос и показывает отправленный curl. Ответ отображается в разделе «Ответы». (Если вы выберете JSON вместо XML в раскрывающемся списке «Тип содержимого ответа», формат ответа будет отображаться как JSON.)
Важно: Petstore — это работающий API, и вы фактически создали питомца. Теперь вам нужно взять на себя ответственность за своего питомца и начать кормить и ухаживать за ним! Это шутка, но большинство пользователей не понимают, что они играют с реальными данными, когда запускают ответы в API (особенно когда они используют свой собственный ключ API). Эти тестовые данные могут быть чем-то, что вам нужно стереть, когда вы переходите от исследования и изучения API к использованию API в реальном мире.
Проверка создания питомца
- Реализация GET/pet/point.
- Нажмите «Попробовать».
- Введите идентификатор животного, который вы использовали в предыдущем упражнении. (Если вы забыли свой идентификатор, см. конечную точку POST Pet, чтобы проверить значение.)
- Нажмите «Выполнить». В ответ мы должны увидеть имя нашего питомца.
Примеры сайтов с документаций по Swagger UI
Прежде чем мы перейдем к другому API с помощью этого руководства по Swagger (в дополнение к демонстрации Petstore), давайте взглянем на другие реализации Swagger:
Некоторые из этих страниц выглядят одинаково, но другие, такие как The Movie Database API и Zomato, легко интегрируются в остальную часть их страницы документации.
Глядя на примеры, бросается в глаза краткость документации в реализации Swagger. Эта краткость связана с тем, что дисплей Swagger спроектирован так, чтобы быть интерактивным, где вы можете опробовать вызовы и увидеть ответы, используя свой собственный ключ API для просмотра ваших собственных данных. этот подход называется «учиться на практике». Кроме того, пользовательский интерфейс Swagger распространяется только на документацию конечной точки. Разделы концепции обычно рассматриваются в отдельном руководстве.
👨💻 Практическое занятие: Создание спецификации OpenAPI в Swagger UI
В этом сеансе мы создадим документацию в пользовательском интерфейсе Swagger в спецификации OpenAPI. Если вы используете один из готовых файлов OpenAPI, вы можете увидеть демонстрацию того, что мы создадим здесь: пользовательский интерфейс OpenWeatherMap Swagger или пользовательский интерфейс Sunrise/Satwer Swagger).
Интеграция спецификации OpenAPI с пользовательским интерфейсом Swagger:
- Подготовьте действительный документ спецификации OpenAPI:
- Инструкции по созданию документа спецификации OpenAPI с нуля см. в справочном руководстве по OpenAPI.
- Чтобы использовать предварительно созданный документ спецификации OpenAPI, вы можете использовать либо файл спецификации OpenWeatherMap, либо файл спецификации API восхода/заката (щелкните ссылку правой кнопкой мыши и сохраните файл YAML на рабочем столе).
Единственная папка, с которой мы будем работать в скачанном zip-архиве, это папка dist (сокращение от дистрибутив). Все остальное используется только при перекомпиляции файлов Swagger, что выходит за рамки данного руководства.
-
Давайте извлечем папку dist из папки swagger-ui-master в другой каталог. (Затем можно удалить папку swagger-ui-master и zip-файл).
Перетащите файл спецификации OpenAPI (из шага 1) в папку dist. (Если вы используете готовые файлы OpenAPI, это файл openapi_openweathermap.yml или openapi_sunrise_sunset.yml. ) Ваша файловая структура должна выглядеть так
ПАРТНЕРСКИЕ АВТОВОРОНКИ. Серьезные комиссии на полуавтомате.9 часов назадМануал "Как добывать море недорогих клиентов из РСЯ"9 часов назад
