Как создать расширение для вашей спецификации открытого API

Что вы делаете, когда вам нужно что-то, с чем OAS не справляется? Конечно же, создайте собственное расширение!

2021 год станет годом API. Мы собираемся сосредоточиться на достижении стандарта (предоставление общедоступных API-интерфейсов) и ускорении темпов внедрения инноваций.

Сосредоточившись на разработке API с помощью Open API Spec (OAS), мы собираемся столкнуться со сценариями, в которых некоторая автоматизация необходима, но в настоящее время невозможна. Может быть, эта автоматизация индивидуальна для вас и вашей компании, или, может быть, это услуга, которую вы хотите предоставить разработчикам во всем мире. Как мы подойдем к реализации этой автоматизации? За счет использования расширения.

Расширение - это простой способ добавить функциональности вашему OAS. Вы добавляете некоторые атрибуты в свой файл, реализуете обработчик для его чтения и выполнения действия и получаете преимущества автоматизации!

Вместо того, чтобы объяснять концептуально, что такое расширение, сегодня я проведу вас через создание совершенно нового. Мы собираемся сделать расширение, которое улучшит генератор тестов контрактов почтальона, который мы сделали некоторое время назад.

Генератор тестов великолепен, но для правильной работы он полагается на засеянные данные. Это означает, что перед выполнением в базе данных должны быть определенные данные, чтобы тесты могли их использовать.

Это вызывает небольшую проблему, потому что увеличивает входной барьер. Было бы неплохо, если бы был способ использовать данные, полученные в результате тестов, в самих тестах. Это означает, что когда генератор выполняет POST для создания новой сущности, он может использовать id этой сущности в последующих запросах к GET или обновлять с помощью PUT.

Давайте подробно рассмотрим, как решить эту проблему, построив пристройку.

Определите бизнес-проблему

В нашем примере мы хотим иметь возможность использовать значения, созданные сгенерированными тестами, в последующих сгенерированных тестах. Бизнес-проблему можно сформулировать следующим образом: «Я хочу использовать динамические переменные в своих тестах, поэтому мне не нужно полагаться на начальные данные».

Определив бизнес-проблему, вы захотите разработать план, как ее лучше всего решить. В нашем случае это предполагает использование значений, созданных генератором тестов, в других запросах.

Для этого мы должны иметь возможность сохранять значения ответов и использовать их в других запросах. Имея это в виду, мы сможем приступить к следующему шагу: определению схемы.

Определите схему расширения

Чтобы использовать динамические переменные, нам нужно знать, когда их сохранять и использовать.

Сохранение динамических переменных

Чтобы сохранить переменную из динамического теста, нам нужно знать, когда и где получить значение из ответа. В нашем примере определенные коды ответа на определенных конечных точках будут давать нужные нам значения.

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

Имея это в виду, следующая схема поддерживает наши бизнес-потребности:

x-postman-variables: 
  - type: save 
    name: myVariable 
    path: .id

В этой схеме type сообщит обработчику, что мы хотим сохранить переменную. name будет именем переменной в Postman. path будет JSON-путем к свойству в ответе. Вы можете видеть, что мы также сделали расширение массивом на тот случай, если нам нужно сохранить несколько значений из одного ответа.

Теперь мы можем добавить расширение в нашу спецификацию Open API под конкретный ответ для конкретной конечной точки. Мы можем сослаться на пример спецификации API Gopher Holes Unlimited.

Потребление динамических переменных

Теперь, когда мы правильно сохранили наши переменные, все сводится к их использованию в последующих тестах. С помощью Open API Spec мы можем определять параметры, используемые в наших запросах.

Поскольку мы хотим использовать переменную в последующих запросах, мы должны обязательно обогатить наш OAS parameters расширением. Каждый раз, когда мы используем параметр, генератор тестов извлекает текущее значение переменной Postman и использует его в тесте.

Использовать значения значительно проще, чем сохранять их, потому что нам просто нужно знать имя переменной. Это приводит нас к следующей схеме:

x-postman-variables: 
  - type: load
    name: myVariable

В этой схеме type сообщает, что мы загружаем значение, а name сообщает нашему обработчику, какую переменную мы хотим. С этим у нас есть определение нашего расширения!

Добавление примера в наш OAS будет выглядеть так:

Реализуйте обработчик

Определив схему расширения, пора написать код, интерпретирующий значения. В конце концов, документ OAS - это всего лишь определение. На самом деле он ничего не делает.

Наше расширение предназначено для использования исключительно с Postman, поэтому наш обработчик будет написан из скриптов предварительного запроса и тестирования в коллекции Contract Test Generator.

Сохранение переменных расширения

Генератор тестов контрактов уже просматривает разрешенные ответы для каждого метода на каждой конечной точке. Чтобы реализовать логику для нашего расширения, мы собираемся привязать эту существующую функциональность.

Когда мы сохраняем ответы для каждого метода, обработчик будет искать расширение и сохранять переменные в свойстве variables в тесте.

Вы можете видеть, что он сохраняет переменные, для которых определен тип save.

Сохранение значений ответа как переменных

Пришло время для самой работы: взять значение из ответа по заданному пути и сохранить его в переменной коллекции Postman.

Опять же, это не очень сложный фрагмент кода. Он просто использует то, что мы сэкономили на шаге 1:

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

Использование значений ответа

Последняя часть нашей головоломки - загрузить только что сохраненное значение, когда это необходимо. В генераторе тестов уже существует функция, которая заменяет параметры предоставленным примером из OAS.

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

Вы можете видеть здесь, что код ищет наше x-postman-variables расширение для любых параметров с типом сохранения load. Если он есть, он будет использовать переменную коллекции. Если нет, то тянет из примера.

Код также был обновлен для параметров запроса и заголовков.

Попробовать

Вот и все! С реализацией обработчика все должно просто работать.

Создать расширение для вашей спецификации Open API очень просто. Всего три простых шага:

1. Определите проблему.
2. Определите схему.
3. Реализуйте обработчик.

Конечно, если вы хотите, чтобы ваше расширение использовалось другими людьми, вам нужно будет задокументировать его использование (например, то, что я здесь делаю!).

Надеюсь, вы вдохновитесь на создание собственного расширения. Возможности безграничны. Обработчику даже не обязательно быть в Postman! Это может быть сценарий в вашем конвейере CI, настраиваемый ресурс в сценарии AWS CloudFormation или даже небольшое настольное приложение по запросу.

Куда бы вы ни пошли, вы обязательно упростите жизнь всей своей команде разработчиков.

Так что идите и создайте несколько расширений! А если еще не сделали, попробуйте генератор тестов. Лучше, чем когда-либо!