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+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. Есть у него и преимущества:

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

Ссылки

• Сайт проекта
• Сайт инициализатора проекта
• Спецификация (оригинал)
• Спецификация (разъяснения)
• Инструментарий для работы с OpenAPI
• Онлайн-редактор OpenAPI
• Сервис OpenAPI с редактором, менеджером файлов и др. возможностями