Спецификация в первую очередь и мок

«Спецификация в первую очередь» значит, что документ OpenAPI появляется раньше кода: вы договариваетесь об API, пробуете его на моке, а когда настоящий сервер появится, сверяете его с тем же документом. В этом руководстве вы добавите спецификацию магазина Alpenglow в рабочее пространство, спроектируете эндпоинт, которого в магазине ещё нет, запустите на своём Mac мок обоих и сверите ответы настоящего API со спецификацией.

• Время: 20 минут.
• Вам понадобится: Echolot и рабочее пространство, например из руководства Ваше первое рабочее пространство или новое пустое.
• Вы узнаете: про страницу «Спецификации», линтер, запросы, следующие за спецификацией, моки и проверку Спецификация OpenAPI.

1. Добавьте спецификациюCopy Anchor Link

Демо-магазин публикует свою спецификацию по адресу https://demo.echolot.dev/openapi.yaml.

1. Сохраните её на Mac. В Терминале:

   Скопировать текст

   curl -o ~/Downloads/openapi.yaml https://demo.echolot.dev/openapi.yaml

   Или откройте адрес в Safari и выберите Файл › Сохранить как….

2. В окне рабочего пространства переключитесь на Спецификации (⌘3).

3. Выберите Добавить файл спецификации… (на пустой странице или в меню + боковой панели) и укажите openapi.yaml. Копия попадёт в папку specs рабочего пространства.

Спецификация откроется в редакторе Визуально: её серверы, эндпоинты, сгруппированные по пути или тегу, и схемы. Переключатель на панели инструментов переходит между Визуально и Код. Оба редактируют один и тот же текст, и сохраняется именно текст.

2. Спроектируйте эндпоинт, которого нет в магазинеCopy Anchor Link

Магазину нужен список его торговых точек. Спроектируйте его до того, как кто-то напишет код.

1. В редакторе Визуально выберите Добавить эндпоинт.

2. В Новый эндпоинт оставьте Метод GET, введите путь /stores, описание List stores и тег Catalog. Нажмите Добавить эндпоинт. Echolot добавит операцию с ответом 200, от которого можно отталкиваться.

3. В редакторе эндпоинта задайте ID операции listStores.

4. Выберите Показать в коде. Замените responses эндпоинта на тело и пример:

   Скопировать текст

         responses:
           '200':
             description: The shop's stores.
             content:
               application/json:
                 schema:
                   type: array
                   items:
                     type: object
                     required: [id, city]
                     properties:
                       id: { type: string }
                       city: { type: string }
                       address: { type: string }
                 example:
                   - { id: zrh, city: Zürich, address: Bahnhofstrasse 1 }
                   - { id: brn, city: Bern, address: Spitalgasse 4 }

Правки сохраняются по мере внесения, а ⌘Z их отменяет. Визуальные правки меняют только строки затронутой записи, поэтому остальной файл, включая комментарии, остаётся таким, как вы его написали. Подробнее — в разделе редактирование спецификаций.

3. Проверьте спецификацию линтеромCopy Anchor Link

Кнопка проблем на панели инструментов показывает зелёную галочку и Проблем нет либо число ошибок и предупреждений.

1. Выберите её. Во всплывающем окне Проблемы сказано, что документ соответствует спецификации OpenAPI и все ссылки разрешаются.
2. Сломайте что-нибудь, чтобы увидеть проблему: в Код замените в одной строке $ref: '#/components/schemas/Product' на '#/components/schemas/Produkt'. Кнопка станет красной. Выберите её и укажите проблему: редактор перейдёт к её строке.
3. Отмените изменение (⌘Z).

Тот же линтер работает в CI с инструментом командной строки. --strict завершает проверку ошибкой и при предупреждениях, а --hints добавляет советы, например о пропущенных ID операций:

echolot spec lint specs/openapi.yaml --strict

4. Создайте запросы, следующие за спецификациейCopy Anchor Link

1. На панели инструментов «Спецификации» выберите Создать запросы. В Запросы появится папка Alpenglow demo shop с папкой на каждый тег (Catalog, Auth, Orders) и запросом на каждый эндпоинт, включая List stores.
2. Посмотрите на Catalog › List products. Его URL — {{baseUrl}}/products. На его вкладке Тесты уже есть две проверки из спецификации: Статус равно 200 и JSON Schema описанного тела.

Папка следует за спецификацией. Когда спецификация позже изменится, меню Запросы на панели инструментов «Спецификации» предложит Проверить изменения для «Alpenglow demo shop»…: оно перечислит, что в спецификации появилось, изменилось и исчезло, и применит это, не затирая ваши собственные правки запросов. См. синхронизацию с OpenAPI.

Созданные запросы начинаются с {{baseUrl}} (строчные rl). Значение для неё вы зададите в следующих двух шагах.

5. Запустите мок спецификацииCopy Anchor Link

1. Переключитесь на Моки (⌘4). Откройте меню + и выберите Мок спецификации «Alpenglow demo shop».
2. Нажмите Старт (⌘R). На панели инструментов появятся зелёная точка и адрес http://127.0.0.1:4010/v1: первый свободный порт начиная с 4010 и базовый путь из сервера спецификации.
3. Выберите Использовать в окружении. Echolot создаст окружение Mock: Alpenglow demo shop, в котором {{baseUrl}} — адрес мока, и выберет его.

Карточка Настройки содержит Порт мока, Отвечать другим устройствам в сети, Задержку перед каждым ответом, долю Ошибок (внедряемые 500) и Проверки: Отклонять запросы, нарушающие спецификацию (400 с причинами). Мок работает, пока окно открыто.

6. Отправьте запросы к мокуCopy Anchor Link

1. Вернувшись в Запросы, отправьте Catalog › List stores. Мок отвечает 200 с двумя точками из вашего примера. На вкладке Заголовки виден Server: Echolot mock.
2. Отправьте Catalog › List products. Примера для него у мока нет, поэтому он строит тело по схеме: правильной формы, но с условными значениями. Обе проверки запроса проходят.
3. В Параметры запроса List products добавьте sort со значением cheapest и отправьте. Мок отклоняет его: 400 с query “sort”: not one of the allowed values. Спецификация допускает name, price, -price и rating. Удалите параметр.
4. В Get a product добавьте заголовок Prefer: code=404 и отправьте. Мок отвечает описанной проблемой 404. Удалите заголовок.

ЖУРНАЛ на странице «Моки» перечисляет каждый запрос, на который ответил мок, с найденной им операцией и возможной проблемой. В карточке Ответы можно сделать так, чтобы операция на каждый запрос отвечала другим описанным статусом или примером. Маршруты на JavaScript для ответов, которым нужно состояние, описаны в разделе маршруты со скриптами.

7. Сверьте настоящий API со спецификациейCopy Anchor Link

1. На странице Окружения добавьте окружение Demo с переменной baseUrl, равной https://demo.echolot.dev/v1, и выберите его в заголовке страницы.
2. Откройте List products, на вкладке Тесты откройте Добавить тест и выберите Спецификация OpenAPI. Заполнять в ней нечего: она проверяет тело по схеме, которую спецификация описывает для вернувшегося статуса.
3. Отправьте. Проходят все три проверки: настоящий магазин соответствует своей спецификации.
4. Отправьте List stores. Настоящий магазин отвечает 404: эндпоинт существует только в спецификации. В этом и смысл подхода «спецификация в первую очередь»: мок позволяет строить на нём уже сейчас.

Чтобы выполнять те же проверки в CI, запустите папку командой echolot run, а мок поднимите там командой echolot mock:

echolot mock specs/openapi.yaml --port 4010

ДальшеCopy Anchor Link

• Спецификации из трафика: напишите спецификацию по запросам, которые вы уже отправляете.
• Моки: примеры, сохранённые из истории, задержки, ошибки и доступ по сети.
• echolot spec: check завершает CI ошибкой, если папка отстала от спецификации.