Как сделать мок сервер
Добавил пользователь Евгений Кузнецов Обновлено: 04.10.2024
Ранее, в качестве способа визуализации документа спецификации OpenAPI, мы изучили опен-сорс проект Swagger UI. Та же компания, которая предлагает бесплатную версию Swagger Editor и Swagger UI (Smartbear), также предлагает премиум-версию с более надежными функциями. Эта премиальная версия редактора Swagger называется SwaggerHub. Разницу этих проектов можно увидеть здесь.
Пример OpenWeatherMap API на SwaggerHub можно посмотреть здесь
Преимущества SwaggerHub
Несмотря на то, что редактор Swagger в сочетании со Swagger UI работает, могут возникнуть проблемы такого плана:
- сложно сотрудничать с другими участниками проекта по спецификации;
- трудно собрать отзывы от рецензентов о конкретных частях спецификации;
- не получится автоматически предоставлять API в бесчисленных структурах кода, где им бы были рады.
При работе с документацией API REST, нужны инструменты, специально разработанные для API-интерфейсов - инструменты, которые позволяют создавать, совместно использовать, совместно работать, создавать версии, тестировать и публиковать документацию способами, не требующими значительной настройки или времени.
В какой-то момент эксперименты с бесплатным инструментом Swagger UI встречают преграду, и нужно найти другой способ для перехода на следующий уровень. Следующий уровень - это SwaggerHub от Smartbear. SwaggerHub предоставляет полное решение для проектирования, управления и публикации документации API способами, которые упрощают жизнь технического писателя API.
Более 15 000 команд разработчиков программного обеспечения по всему миру используют SwaggerHub. Поскольку спецификация OpenAPI становится в большей степени отраслевым стандартом для документации API, специфичные инструменты SwaggerHub имеют важное значение.
Вступление SwaggerHub и его Дэшборд
Smartbear - это компания, которая поддерживает и разрабатывает инструменты Swagger с открытым исходным кодом (Swagger Editor, Swagger UI, Swagger Codegen и др.). Они также сформировали инициативу OpenAPI, которая ведет эволюцию спецификации Swagger (OpenAPI).
Smartbear разработал SwaggerHub как способ помочь командам совместно работать над спецификацией OpenAPI. Многие из клиентских и серверных SDK могут быть автоматически сгенерированы из SwaggerHub, и существует множество дополнительных функций, которые можно использовать при разработке, тестировании и публикации своего API.
На панели инструментов отображается список созданных API. В этом примере виден API OpenWeatherMap, который используется на протяжении всего этого курса.
Редактор SwaggerHub
SwaggerHub содержит тот же редактор Swagger, к которому можно получить доступ онлайн. Этот редактор предоставляет проверку в реальном времени, при работе над спецификацией API. Однако, в отличие от отдельного редактора Swagger, в Swagger Editor SwaggerHub можно переключаться между несколькими режимами:
- Скрыть навигацию;
- Скрыть редактор и навигацию;
- Скрыть UI Docs.
Самое главное в редакторе, SwaggerHub позволяет сохранять свою работу. В бесплатном редакторе Swagger контент хранится в кеше браузера, без возможности сохранения файла в облаке. Если кеш почистить, то контент исчезнет. При использовании автономного редактора Swagger, после окончания работы надо копировать содержимое из редактора Swagger в файл на своем компьютере.
С помощью SwaggerHub можно хранить документ со своей спецификацией непосредственно на серверах SwaggerHub или ссылаться на него и сохранить его во внешнем источнике, таком как GitHub.
Версии
SwaggerHub позволяет не только хранить спецификацию OpenAPI, но и сохранять различные версии спецификации. Это значит, что можно поэкспериментировать с новым контентом, добавив новую версию. Можно вернуться к любой версии, а также опубликовать или отменить публикацию любой версии.
Варианты управления версиями файла OpenAPI
При публикации версии, опубликованная версия становится доступной только для чтения. Если нужно внести изменения в опубликованную версию (а не создавать новую версию), можно отменить публикацию версии и внести в нее изменения.
Управление версиями полезно, при работе над спецификацией с другими членами команды. Например, предположим, что оригинальная версия была составлена инженером, а мы хотим внести существенные изменения. Вместо того, чтобы напрямую перезаписывать содержимое (или делать резервную копию автономного файла), можно создать новую версию, а затем взять на себя больше прав, чтобы пересмотреть эту версию со своими обновлениями, не опасаясь, что инженер отреагирует отрицательно на перезаписанный / потерянный файл.
Встроенное комментирование/обзор
Ключ к процессу рецензирования - это возможность для членов команды комментировать спецификацию, как в Google Docs и ее аннотации на полях. При работе в редакторе SwaggerHub, слева от каждой строки расположен небольшой знак + . Чтобы добавить комментарий к строке надо нажать кнопку + .
Встроенные функции комментирования и ответа на SwaggerHub
При нажатии на + , справа появляется панель комментариев, где можно оставить комментарии, и получить ответы. Пользователи могут редактировать, удалять или разрешать комментарии. Функция комментирования помогает облегчить процесс обзора таким образом, чтобы тесно интегрироваться с контентом. Панель комментариев можно сворачивать или показывать по желанию.
Немногие инструменты поддерживают встроенные аннотации, подобные этой, и было бы невозможно без базы данных хранить комментарии вместе с профилями, связанными с рецензентами. Эту функцию было бы утомительно реализовать самостоятельно, поскольку для этого потребовалась бы база данных и механизм аутентификации. Все это включено в SwaggerHub.
Авто генерация клиентского SDK
Еще одним преимуществом SwaggerHub является возможность автоматической генерации необходимого клиентского или серверного кода из спецификации. Клиентские SDK предоставляют инструменты, необходимые для выполнения запросов API на определенных языках программирования (таких как Java или Ruby).
В верхнем правом углу по нажатию на стрелку вниз можно выбрать Client или Server. Пользователи имеют доступ к созданию клиентских и серверных SDK в более чем 30 форматах.
Возможности экспорта клиентских и серверных SDK
Предположим, что пользователь реализует наш REST API в приложении Java. Пользователь может выбрать загрузку клиентского SDK Java для расширенного кода, демонстрирующего реализацию нашего API на Java. Другие варианты включают Ruby, Android, Go, CSharp, JavaScript, Python, Scala, PHP, Swift и многие другие.
Некоторые сайты API документации выглядят впечатляюще, так как демонстрируют реализации для разных языков программирования. SwaggerHub берет эти языки программирования и умножает их в десять раз, чтобы обеспечить каждый возможный вывод, который может пожелать пользователь.
На выходе получаем простой пример кода, показывающий, как вызвать конечную точку REST на выбранном языке. Вывод включает в себя целый SDK, состоящий из различных деталей реализации на этом языке. (Для получения дополнительной информации о SDK см. SDK и примеры приложений )
Предоставление кода ускоряет реализацию для разработчиков и помогает масштабировать не зависящий от языка REST API для большего числа платформ и пользователей.
Экспорт в HTML
Среди множества возможностей SwaggerHub для генерации файлов клиента и SDK есть опция экспорта HTML. Можно экспортировать спецификацию OpenAPI в виде статического HTML-файла в одном из двух стилей: HTML или HTML2.
Демо экспорта API OpenWeatherAPI можно увидеть здесь: HTML или HTML2. Оба варианта генерируют весь контент в файл index.html.
Экспорт HTML является более простым выводом, чем HTML2. Потенциально можно включить вывод HTML в другую документацию, например, так, как Cherryleaf сделал при импорте Swagger в Flare. (Возможно, придется убрать часть кода и предоставить стили для различных элементов документации, и пользователи не смогут это опробовать) О способах интеграции узнаем больше в разделе Интеграция Swagger с документацией.
Экспорт HTML2 больше предназначен для самостоятельной работы, поскольку имеет фиксированную левую боковую панель для навигации по конечным точкам и навигационным таблицам, показывающую шесть различных примеров кода:
Экспорт HTML2
Для обоих выводов потребовалась бы здоровая доза индивидуального стиля, чтобы их можно было использовать.
Мок-серверы
Еще одна интересная особенность SwaggerHub - возможность создавать мок-серверы API. Предположим, есть API, в котором мы не хотим, чтобы пользователи генерировали реальные запросы. (Возможно, это система заказов, где пользователи могут заказывать продукты через API, или у нас нет тестовых аккаунтов / систем). С помощью мок-сервера можно моделировать ответы, которые позволят пользователям получить представление о том, как работает ваш API.
Имитация API может быть особенно полезна для тестирования API с бета-пользователями. Одна из причин, по которой многие люди пишут свои API с помощью спецификации, прежде чем писать какие-либо строки кода (следуя философии “spec-first development”, описанной Майклом Стоу ), заключается в том, чтобы избегать кодирования API с конечными точками и ответами, которые не нужны пользователям.
Используя подход Мок-сервера, SwaggerHub не только предоставляет документацию, но и выступает в качестве инструмента бета-тестирования, позволяющего разработать дизайн API прямо перед тем, как потратить тысячи часов на реальное кодирование. Можно включить автоматическое моделирование для разных версий API, создавая варианты и тестируя каждый из них.
Переиспользование контента (Домены)
Еще одна особенность, доступная исключительно в SwaggerHub, - это концепция доменов. Домены - это повторно используемые фрагменты кода, которые можно использовать, чтобы избежать дублирования в спецификации.
Использование домена минимизирует дублирующийся контент и позволяет быть более последовательным и эффективным. О доменах можно прочитать больше в разделе Домены.
Организации и проекты
Совместная работа SwaggerHub - это самая распространенная причина, по которой люди переходят с опен-сорс инструментов на SwaggerHub. Может быть много разных инженеров, работающих над различными API в SwaggerHub. Чтобы организовать работу, можно сгруппировать API в организации, а затем добавить участников в соответствующую организацию. Когда этот участник входит в SwaggerHub, он или она будет видеть только те организации, к которым у него есть доступ.
Организация проектов по командам
Такой аспект организаций и проектов может показаться несущественным, если есть только один или два API, но стоит подумать об этом, при наличии десятков API и нескольких команд. Для таких сценариев становятся важными функции организации и проекта.
Расширяем роль технического писателя с помощью API
Технические писатели позиционируются как сильные игроки в философии “spec-first development” в дизайне OpenAPI. Становясь экспертами в кодировании спецификации OpenAPI и знакомясь с надежными инструментами для совместной работы, такими как SwaggerHub, технические писатели могут руководить командами разработчиков не только посредством создания и усовершенствования документации API, но и прокладывать путь для бета-тестирования, проверки спецификаций, клиент-серверного SDK поколения и т.д.
Разработка полнофункциональной, “high-level” спецификации OpenAPI лежит в основе этих усилий. Немногие инженеры знакомы с созданием этих спецификаций, и технические писатели, которые умеют как создавать спецификацию, так и настраивать инструменты Swagger, могут выполнять критически важные роли в командах разработки API.
Хорошие инструменты не бесплатны. SwaggerHub действительно стоит денег, но это стоит того. Бесплатные инструменты часто заброшены, плохо обслуживаются, и им не хватает документации и поддержки. Используя платный инструмент от надежной компании API (той же самой компании, которая поддерживает инструменты Swagger и спонсирует спецификацию OpenAPI), можно подключиться к инфраструктуре, необходимой для масштабирования усилий по документированию API.
Аналогичный функционал можно реализовать с помощью любого веб-сервера.
Если не хотите связываться с SOAP UI - советую прочитать статью Flask
File → Create Empty Project
Введите имя проекта
New Rest Mock Service
Укажите имя MockService
Add new mock action
Введите путь и выберите метод GET
Введите имя нового ответа
Скопируйте json и вставьте в тело ответа
Правой кнопкой мыши кликните на BicycleService и
Add new mock action
create New MockResponse
Скопируйте json и вставьте в тело ответа
Скопируйте json и вставьте в тело ответа
Обратите внимание, что сервис BicycleService использует порт 8080
Запустите BicycleService нажав на зелёный треугольник
У нас есть четыре сценария
Используем Postman чтобы протестировать их
Должен вернуть key 12041961
Должен вернуть список велосипедов
Должен вернуть первый велосипед
Dynamic Response
Чтобы заменить статичный ответ 12041961 на динамический в запросе POST на /bicycle заменим 12041996 на $ и в script добавим следующий код:
Чтобы протестировать отправим несколько запросов из Postman и проверим изменяется ли ответ
Вот сценарий: Я инженер по обеспечению качества, и наш продукт основан на веб-технологиях. У нас есть несколько сценариев автоматизации для тестирования веб-сайтов, и они будут взаимодействовать с API серверной части. Мы хотим, чтобы, когда некоторые действия на веб-сайте вызывали некоторые серверные API, настоящий API НЕ вызывается, но он переходит на фиктивный сервер и возвращает поддельные данные. Я знаю, что в настоящее время в коде разработчиков нет макета. Я хочу настроить фиктивный сервер, который будет перехватывать запросы и фактически возвращать некоторые предопределенные данные.
Есть ли какие-либо предложения или какой-либо зрелый макет сервера с открытым исходным кодом для этого сценария и где должен быть настроен фиктивный сервер?
Можете ли вы использовать другой IP-адрес для сервера Только в тестовой среде?
Я не понял твоей точки зрения. Вы имеете в виду веб-сервер или какой-то другой сервер?
Я имел в виду - веб-сервер, с которым общается клиентская сторона.
Я думаю, это зависит от того, где запущен фиктивный сервер. Я думаю, что в моей тестовой среде фиктивный сервер можно было бы настроить на другой виртуальной машине Linux.
В этой статье я рассказываю о том, как мы пришли к тому, что сейчас можем деплоить UI в песочницу по каждому коммиту и при этом не переживая за доступность бекенда и его консистентность.
Для локальной разработки я предпочитаю мокать данные от сервера. Это даëт ряд преимуществ, об одном из которых я хотел бы поговорить подробней.
Когда стартует новый проект, как правило, бекенд еще не готов и чтобы полноценно разрабатывать свое приложение, приходится прибегать к мокам. Я нашел для себя достаточно удобную схему организации такой работы.
Типичный проект, с которым я имею дело сейчас и для которого буду описывать схему:
- Single Page Application
- RESTfull API
- наличие GIT/CI/окружений (environments)
Вся реализация основана на специфике мок сервера. Подходов к его реализации было несколько, на текущем проекте удалось реализовать его минимальную версию.
Итак, базовая идея нынешней реализации в том, что мок сервер — полностью статический. Сперва это может показаться странным, но для 90% наших задач — статического сервера достаточно.
Идея сервера предельно проста.
Допустим, у нас есть ендпоинт /api/asset/ , он умеет стандартный CRUD. На файловой системе такой сервер будет выглядеть следующим образом:
В зависимости от типа запроса, отдается REQUEST_METHOD.json файл, за него отвечающий.
Минимальная имплементация такой логики на node.js будет выглядеть так:
Собственно говоря, теперь у нас есть свой сервер, который умеет отвечать на запросы GET:/api/asset/123 , POST:/api/asset/123 , DELETE: /api/asset/123 .
Простота идеи, статичность моковых данных и легкость реализации сервера дает нам возможность двигаться дальше.
Мы храним моки прямо в репозитории с UI, поэтому у нас не возникает проблем со стартом новой фичи, если она требует отдельный ответ от сервера. Мы его мокаем и начинаем разработку (главное не забывать договориться о формате данных с бекендом)
C локальной разработкой разобрались, теперь можно перейти к CI.
У нас в репозитории лежит UI + моки бекенда — этого достаточно, чтобы при билде приложения выливать его на некий сервер и получить возможность открывать UI и смотреть что там поменялось или как оно работает еще до того, как изменения вольются в мастер и раскатаются на demo\dev серверах.
Первое, что хотелось — это конечно, же избавиться от node.js сервера. Он удобен в локальной разработке, но подымать новый инстанс ноды при каждом коммите показалось избыточным. Поэтому для реализации demo сервера пришлось пойти немного другим путем.
Финальная реализация получилась следующей:
— UI и *.json от мок сервера хранятся на S3.
— Перед ними поднят один nginx сервер, который маршрутизирует весь входящий трафик, и в котором реализована базовая логика node.js сервера.
— Этот же nginx сревер маршутизирует трафик на реальный dev сервер, по дополнительному адресу.
Как это выглядит на практике.
1) при коммите, запускается pipeline который гоняет все тесты
2) если пройдены все тесты и проверки, то собирается приложение с baseUrl вида /ci/commit-hash/ (важный момент, вы должны сконфигурировать ваше приложение так, чтобы оно умело работать и из-под папок, а не только из корня домена)
3) после чего приложение выливается на S3 в папку /ci/commit-hash/
4) моки выливаются в папку /ci/commit-hash/api/
Сервер настраивается один раз и запускается в единственном экземпляре. У нас он крутится на минимальной EC2 или AWS Free Tier.
Особенности данного конфига:
Примерно в такой конфигурафии сейчас работат наш проект. Разумеется, mock сервера подходят не для всех проектов, но если есть возможность ими пользоваться — пользуйтесь, они дают много возможностей. Идвидидуальный деплой — одна из них.
Читайте также: