Первая страница

OpenAPI - введение

спецификация, инструменты, визуализация
Онлайн: РИСОВАЛКИ | ИГРЫ | РЕЛАКС программы

Анатолий Опарин / февраль, 2019

OpenAPI (изначально Swagger) — формализованная спецификация и экосистема множества инструментов, предоставляющая интерфейс между front-end системами, кодом библиотек низкого уровня и коммерческими решениями в виде API. Вместе с тем, cпецификация построена таким образом, что не зависит от языков программирования, и удобна в использовании как человеком, так и машиной.

С помощью OpenAPI заказчик сервиса и его разработчик могут точно и непротиворечиво описывать и договариваться о REST запросах - что запрос передает, что получает, какие переменные участвуют в запросе, какие ограничения накладываются на элементы запроса, какова типизация запросов и ответов.
Заказчик сервиса, владеющий искусством написания OpenAPI файлов, может таким образом писать ТЗ разработчику. Разработчик с помощью OpenAPI может документировать уже созданный и действующий API. OpenAPI позволяет совмещать в одном файле код и документацию и разделять их для просмотра в удобном виде с помощью инструментов визуализации.
OpenAPI представление избавляет исследователя API от необходимости залезать в программный код разработчика.

С какими аспектами OpenAPI следует быть знакомым:

  • Спецификация
  • Написание кода
  • Визуализация
  • Тестирование

Спецификация

Согласно спецификации API описывается в виде дерева параметров. Есть обязательные параметры, есть рекомендуемые и опциональные. Спецификация позволяет описать:

  • Доступные конечные точки (например, /users) и операции на каждой точке (например, GET/users, POST/users);
  • Параметры на входе и на выходе для каждой операции;
  • Методы аутентификации;
  • Контактную информация, лицензию, условия использования и другую информацию...

Параметр спецификации может быть: объектом, списком (простым массивом), строкой, ссылкой.
Значения параметра, например, переменной, участвующей в операции, описываются типом данных, возможными значениями, ограничениями, примерами...
Для многих узлов есть параметры description и/или summary с помощью которых можно в свободном стиле вести документацию API.

Представления спецификации:

Процедурно-ориентированное описание – Оригинал спецификации!
Это объемный и разветвленный документ, в котором подробно представлены правила описания REST API. Документ по ссылке имеет древовидную логику, но не древовидное представление. Это затрудняет его изучение, заставляя читателя перепрыгивать по ссылкам. Например, в качестве описания какого-то параметра дается список его подпараметров и с каждого подпараметра организована ссылка на уже его подпараметры, которые находятся по тексту ниже. Таким образом, читатель может перемещаться по документу только в одном измерении по вертикали.

Функционально-ориентированное описание – С сайта проекта.
Это подробные разъяснения позиций спецификации, представленные в формате руководства пользователя, когда в левом сайдбаре размещается содержание в виде разделов, а справа тело активного раздела. Так восприятие подаваемой информации воспринимается несколько легче предыдущего случая.

Ментальная карта – Интерактивная визуальная карта.
Для некоторого облегчения навигации по системе параметров OpenAPI я создал интерактивную древовидную карту, которая позволяет с удобством перемещаться уже в двух измерениях - по вертикали и горизонтали - одноуровневые узлы дерева идут вертикально, а дочерние узлы открываются уже по горизонтали вправо. Эту карту можно использовать как быстрый справочник для проверки корректности иерархии и синтаксиса создаваемого OAS-файла. Карта загружается локально в лице одного HTML-файла и просматривать ее можно с помощью браузера. Вот фрагмент карты:

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

Ментальная карта с комментариями – Интерактивная карта с описанием узлов.
От предыдущей карты отличается прежде всего тем, что по каждому узлу карты есть подробный текстовой комментарий. Скачивание на локальный компьютер не предусмотрено. Вот фрагмент карты:

Возможности навигации: • масштабирование • открытие/сворачивание ветки • внешние ссылки из блока комментария по узлам.

Написание кода

Спецификация реализуется через текстовой файл, написанный в форматах YAML или JSON. По сути YAML - это тот же JSON с более строгим и компактным синтаксисом. Естественно создать такой файл можно в любом текстовом редакторе, начиная с базового Блокнота. Но писатель хочет комфорта и верификации написанного, поэтому, стремится использовать специализированные редакторы кода или IDE (в последующем просто "редактор"). Многие редакторы поддерживают форматы YAML или JSON для подсветки синтаксиса из коробки или с помощью плагинов, но не для всех написаны плагины-линтеры для осуществления синтаксической проверки кода на предмет ошибок. И считанные единицы умеют красиво и удобно визуально интерпретировать OpenAPI.

Кроме подсветки и указания на ошибки в специализированных редакторах укрепилась функция сворачивания/разворачивания блоков кода, а именно блоков, которые имеют вложенные элементы. Это удобно для быстрой временной очистки места на рабочем поле редактора.

Функция автоподстановки также часто встречается и позволяет быстро вспомнить и вставить нужное ключевое слово в текст.

Самые распространенные редакторы, которые поддерживают в той или иной степени JSON, и/или YAML, и/или OpenAPI:

  • Atom (с плагином linter-swagger)
  • Brackets (с расширением YAML)
  • Notepad++
  • Sublime Text (с плагином Pretty YAML)
  • Visual Studio Code (с плагинами openapi-designer, openapi-lint и YAML)
  • Eclipse (с проинсталлированным KaiZen OpenAPI Editor)
  • NetBeans
  • Intellij IDEA (с плагином Senya Editor)

Визуализация

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

  • Устанавливать:
    1. вызвать панель расширений по нижней кнопке слева или при помощи горячих клавиш Ctrl+Shift+X;
    2. в строке поиска набить "openapi";
    3. в списке найденных по контексту возможных для установки расширений найти openapi-designer и нажать кнопку Install в его блоке;
    4. после установки перегрузить программу (можно по кнопке Reload requered).
  • Вызывать:
    1. открыть YAML файл в нотификации OpenAPI;
    2. вызвать панель расширений сочетанием горячих клавиш Ctrl+Shift+P;
    3. в поисковой строке набрать "openapi", чтобы отобрать в списке расширения по контексту;
    4. выбрать OpenAPI Designer: Preview;
    5. в правой половине экрана откроется окно с визуализацией кода.

При следующих вызовах Ctrl+Shift+P нужная команда будет уже на первом месте в списке.

Обновление окна визуализации в VS Code происходит не автоматически по ходу набора текста, а после сохранения файла, например, по Ctrl+S. В визуализаторе даже можно сразу протестировать описываемый API запрос к указанному (в узле servers: url:) серверу, если на вашем компьютере установлена утилита curl, через которую идет запрос к серверу. Визуализатор показывает ошибки кода в верхней половине своего окна, но ссылки на ошибки почему-то нерабочие.

Есть еще расширение OpenAPI Preview, которое в вопросе визуализации YAML-OpenAPI кода работает аналогично расширению openapi-designer, но больше ничего делать не умеет. Даже ошибки не показывает.

Расширение openapi-lint призвано следить за правильностью синтексиса и за генерацией автодополнения кода. Оно у меня установилось, но результат его работы меня как-то не удовлетворил. Во-первых, проверка проводится не на лету, а после вызова валидатора (Ctrl+Shift+POpenAPI 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. Есть у него и преимущества:

  • изменения, вносимые в код в левом окне, тут же отображаются в правом окне визуализации без дополнительных манипуляций;
  • есть рабочие ссылки, которые из окна визуализации перебрасывают пользователя в окно кода на релевантную строку;
  • при фиксации ошибок спецификации генерится рабочая ссылка на строку с ошибкой;
  • можно переходить по ссылкам из поля $ref;
  • редактор бесплатен.

Эти фичи повторяются по сравнению с редакторами кода: ? подсветка синтаксиса ? сворачивание/разворачивание кода.

Swagger Editor можно скачать на свой компьютер и пользоваться через браузер локально!

SwaggerHub

Кроме того, есть проект SwaggerHub, который предлагает зарегистрированным пользователям некоторые дополнительные фичи по сравнению со Swagger Editor:

  • Во-первых, в аккаунте пользователя могут создаваться, редактироваться и храниться разные OpenAPI файлы. Есть менеджер файлов, который приобретает актуальность при большом количестве файлов.
  • Во-вторых, редактор OpenAPI имеет дополнительную панель навигации непосредственно по коду, имеет возможность оставлять комментарии.
  • В-третьих, есть шаблоны для новых API

Ценовая политика: На бесплатном тарифе предусмотрены ограничения на количество API файлов. На двух платных тарифах всё лучше.

Недоумение: в файловом менеджере нельзя удалить файл API.

Тестирование

С тестированием не разбирался, но есть решения, которые на основе openapi файла готовы отсылать запросы на сервер, указанный в servers: url:, и показывать ответы сервера.

Например, в описанных выше визуализаторах есть кнопка Try it out, расположенная в блоке каждого запроса. Если нажать на нее, то ниже появляется поле для ввода параметра (в него автоматически подставляется значение примера из paths: <запрос>: get: parameters: schema: example:) и кнопка Execute. После нажатия на кнопку Execute визуализатор отправляет запрос с данным параметром на сервер с помощью утилиты curl и показывает ответ сервера.

Есть утилита • https://www.npmjs.com/package/test-openapi

Есть онлайн-сервисы: • Swagger inspectorDreddAssertible...

Ссылки

Новости
Творческой личности
домой | живопись | графика | компьютерная графика | поделки | юные художники | темы | комментарии | перлы
конкурсы | игры | релакс | рисовалки | учиться рисовать | детские карты Москвы | детские стихи | статьи | видео | поиск | обратная связь