|
OpenAPI – введениеспецификация, инструменты, визуализация |
|
Онлайн: РИСОВАЛКИ | ИГРЫ | РЕЛАКС программы |
Анатолий Опарин / февраль, 2019 OpenAPI (изначально Swagger) — формализованная спецификация и экосистема множества инструментов, предоставляющая интерфейс между front-end системами, кодом библиотек низкого уровня и коммерческими решениями в виде API. Вместе с тем, cпецификация построена таким образом, что не зависит от языков программирования, и удобна в использовании как человеком, так и машиной. С помощью OpenAPI заказчик сервиса и его разработчик могут точно и непротиворечиво описывать и договариваться о REST запросах – что запрос передает, что получает, какие переменные участвуют в запросе, какие ограничения накладываются на элементы запроса, какова типизация запросов и ответов. С какими аспектами OpenAPI следует быть знакомым:
СпецификацияСогласно спецификации API описывается в виде дерева параметров. Есть обязательные параметры, есть рекомендуемые и опциональные. Спецификация позволяет описать:
Параметр спецификации может быть: объектом, списком (простым массивом), строкой, ссылкой. Представления спецификации: ▢ Процедурно-ориентированное описание – Оригинал спецификации! ◫ Функционально-ориентированное описание – С сайта проекта. ▤ Ментальная карта – Интерактивная визуальная карта. Возможности навигации: • масштабирование • контекстный поиск по всем элементам карты • перемещение в любом направлении с помощью мыши • открытие/сворачивание ветки • открытие дочерних узлов заданного уровня вложенности • перекрестные внутренние ссылки с узла на узел • внешние ссылки. ▦ Ментальная карта с комментариями – Интерактивная карта с описанием узлов. Возможности навигации: • масштабирование • открытие/сворачивание ветки • внешние ссылки из блока комментария по узлам. Написание кодаСпецификация реализуется через текстовой файл, написанный в форматах YAML или JSON. По сути YAML – это тот же JSON с более строгим и компактным синтаксисом. Естественно создать такой файл можно в любом текстовом редакторе, начиная с базового Блокнота. Но писатель хочет комфорта и верификации написанного, поэтому, стремится использовать специализированные редакторы кода или IDE (в последующем просто "редактор"). Многие редакторы поддерживают форматы YAML или JSON для подсветки синтаксиса из коробки или с помощью плагинов, но не для всех написаны плагины-линтеры для осуществления синтаксической проверки кода на предмет ошибок. И считанные единицы умеют красиво и удобно визуально интерпретировать OpenAPI. Кроме подсветки и указания на ошибки в специализированных редакторах укрепилась функция сворачивания/разворачивания блоков кода, а именно блоков, которые имеют вложенные элементы. Это удобно для быстрой временной очистки места на рабочем поле редактора. Функция автоподстановки также часто встречается и позволяет быстро вспомнить и вставить нужное ключевое слово в текст. Самые распространенные редакторы, которые поддерживают в той или иной степени JSON, и/или YAML, и/или OpenAPI:
ВизуализацияОдной из основных идей появления OpenAPI является желание автоматически генерировать из текстового файла, созданного строго по спецификации, удобный и наглядный интерфейс API. Поэтому от редактора требуется поддержка OpenAPI. Многие редакторы из вышеприведенного списка об этом заявляют, но не со всеми удалось поработать успешно. Понравились Visual Studio Code и Intellij IDEA. В них визуальное представление YAML файла, созданного по спецификации OpenAPI, очень доходчиво, точно как на сайте проекта в онлайн-редакторе https://editor.swagger.io/ Visual Studio CodeПо нашей теме Visual Studio Code требует установки расширений openapi-designer, openapi-lint и YAML. На примере расширения openapi-designer, которое отвечает за визуальное представление кода, покажем как расширение устанавливать и вызывать на действие:
При следующих вызовах Ctrl+Shift+P нужная команда будет уже на первом месте в списке. Обновление окна визуализации в VS Code происходит не автоматически по ходу набора текста, а после сохранения файла, например, по Ctrl+S. В визуализаторе даже можно сразу протестировать описываемый API запрос к указанному (в узле servers: url:) серверу, если на вашем компьютере установлена утилита curl, через которую идет запрос к серверу. Визуализатор показывает ошибки кода в верхней половине своего окна, но ссылки на ошибки почему-то нерабочие. Есть еще расширение OpenAPI Preview, которое в вопросе визуализации YAML-OpenAPI кода работает аналогично расширению openapi-designer, но больше ничего делать не умеет. Даже ошибки не показывает. Расширение openapi-lint призвано следить за правильностью синтексиса и за генерацией автодополнения кода. Оно у меня установилось, но результат его работы меня как-то не удовлетворил. Во-первых, проверка проводится не на лету, а после вызова валидатора (Ctrl+Shift+P ➜ OpenAPI Validate). Во-вторых, при обнаружении ошибки этот валидатор просто сообщает в нижнем правом углу, что документ невалидный, и всё. А вот расширение YAML реально работает – проверяет код на соответствие синтаксису YAML и в случае его нарушения тут же сообщает об ошибках в нижней панеле Problems. Если этой панели не видно, то её можно вызвать с помощью горячих клавиш Ctrl+Shift+M. Скриншот, иллюстрирующий работу Visual Studio Code с OpenAPI: Intellij IDEAПо нашей теме требуется установить расширение Senya Editor. С помощью него также производится качественная визуализация YAML или JSON файла, выполненного по спецификации OpenAPI. Недастаток этого расширения также как и у Intellij IDEA – в его платности. Senya Editor имеет trial период. Работает это расширение аналогично openapi-designer в VS code. Swagger EditorЭто онлайновый редактор на сайте разработчика спецификации. Он лишен некоторых достоинств десктопных редакторов кода, но по существу является очень удобным и надежным инструментом для работы с OpenAPI. Есть у него и преимущества:
Эти фичи повторяются по сравнению с редакторами кода: • подсветка синтаксиса • сворачивание/разворачивание кода. Swagger Editor можно скачать на свой компьютер и пользоваться через браузер локально! SwaggerHubКроме того, есть проект SwaggerHub, который предлагает зарегистрированным пользователям некоторые дополнительные фичи по сравнению со Swagger Editor:
Ценовая политика: На бесплатном тарифе предусмотрены ограничения на количество API файлов. На двух платных тарифах всё лучше. Недоумение: в файловом менеджере нельзя удалить файл API. ТестированиеС тестированием не разбирался, но есть решения, которые на основе openapi файла готовы отсылать запросы на сервер, указанный в servers: url:, и показывать ответы сервера. Например, в описанных выше визуализаторах есть кнопка Try it out, расположенная в блоке каждого запроса. Если нажать на нее, то ниже появляется поле для ввода параметра (в него автоматически подставляется значение примера из paths: <запрос>: get: parameters: schema: example:) и кнопка Execute. После нажатия на кнопку Execute визуализатор отправляет запрос с данным параметром на сервер с помощью утилиты curl и показывает ответ сервера. Есть утилита • https://www.npmjs.com/package/test-openapi Есть онлайн-сервисы: • Swagger inspector • Dredd • Assertible... Ссылки
Ещё обзоры для вебмастеров, расширяющие их технологический кругозор: • Памятка начинающему вебмастеру • Amazing Slider – программа для создания HTML5 слайдшоу, галерей, альбомов • Blumentals WeBuilder – удобнейший редактор кода с предпросмотром • Camtasia Studio – видеоредактор с экспортом в интерактивный HTML5 проигрыватель • GDevelop – игровой движок c редактором в вебе, на мобильных и ПК платформах • Google Web Designer – конструктор HTML5 баннеров и приложений • Flip PDF – конвертор PDF документов в HTML5 приложение • Hi Slider – программа для создания продвинутых jQuery слайдеров • Hippani Animator – удобная анимационная студия с экспортом в HTML, video, анимированный gif • Lunacy – для макетирования интернет-страниц • Moodle – практика администратора СДО • MediaWiki – как использовать для ведения и хранения документации • MediaWiki – как скачивать Wiki-страницы в PDF • MediaWiki – как подсвечивать синтаксис программного кода • Nicepage – конструктор сайтов и тем для CMS • Pinegrow – стильный визуальны конструктор сайтов • PowerPoint в HTML5 – обзор софта конвертации • RocketCake – лаконичный визуальный конструктор сайтов • Saola Animate – программа для быстрого и удобного создания анимации в HTML5 • Scratch – визуальный язык программирования и редактор кода • Sozi – программа для создания стильных HTML5 презентаций с перелетами между слайдами • SVG – как сделать анимацию линии (имитацию рисования) • Tilda – самый удобный онлайновый конструктор сайтов, плюсы и минусы • TimelineJS – библиотека для хронологических лент • TurboSite – лаконичный конструктор многостраничных сайтов • TurboWarp – продвинутый форк Scratch для создания HTML5 игр и приложений • WOW Slider – программа для создания красивых HTML5 слайдеров • WYSIWYG Web Builder – мощный визуальный конструктор сайтов • Yonote – веб-сервис для организации базы знаний • HTTP – коротко о протоколе • Визуально-блочные среды программирования и моделирования – обзор • Инструменты для создания прототипов интернет-страниц: Axure и ProtoShare • Что нужно знать об электронных платежах вебмастеру интернет-магазина • Как создать интерактивный кроссворд на сайте? • Как работать с Flash в современное время • Спецсимволы HTML – коды около 2000 дизайнерских иконок |
|
|