Анализ HTTP API, документирование в OpenAPI и переиспользование в Postman

02.11.20

Интеграция - WEB-интеграция

В статье опишу порядок работы с описанием HTTP API на примере подсистемы "Получение обновлений программы" из БСП 3.

Вводные

  • БСП 3.1.3.17
  • Желание разобраться в механизме автоматического получения патчей и обновления типовых конфигураций
  • Статья с началом разбора темы //infostart.ru/1c/articles/1317652/
  • Отсутствие документации на сервис

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

 

Формирование описания

Для документирования буду использовать OpenAPI спецификацию (ссылка) и формат YAML. В качестве редактора использую VS Code c модулем OpenAPI Editor (ссылка), возможно работать в online редакторе (ссылка). В общем автозаполнение для OpenAPI работает хуже чем для RAML и формирование документации вручную более трудоемко, но это спецификация более распространена среди разработчиков и инструментов.

Источником информации будет общий модуль ПолучениеОбновленийПрограммы

Общее описание

Создаем заголовок файла

openapi: '3.0.2'
info:
  title: API Сервиса автоматический обновлений 1С
  version: '1.0'

Сервера сервиса описаны в функции ХостСервисаОбновлений()

Добавляем в описание

servers:
  - url: https://update-api.1c.ru
  - url: https://update-api.1c.eu

 

Компоновка запроса производится в функции URLОперацииСервисаОбновлений(), в которой указан базовый адрес. В OpenAPI нет иерархии запросов, каждая точка подключения указывается от корня, группировка произодится по тегам. Добавляем базовый адрес в блок servers 

servers:
  - url: https://update-api.1c.ru/update-platform
  - url: https://update-api.1c.eu/update-platform

 

Список URL

Проходим поиском с "URLОперацииСервисаОбновлений" по модулю, получаем список URL из функций, и названия функций, которые переносим в описание. Формируем блок patch, на данный момент он валидный, но не рабочий, потому что в нем не указаны методы и ответы.

paths:
  /programs/update/ping:
    description: Ping
  /programs/update/info:
    description: Info
  /programs/update/:
    description: Файлы обновлений
  /patches/getInfo:
    description: Доступные исправления
  /patches/getFiles:
    description: Файлы исправлений

 

Проверка доступности сервиса

URLОперацииPing используется для формирования переменной "ПроверитьДоступностьСервиса", запускается через функцию ИнтернетПоддержкаПользователей.ЗагрузитьСодержимоеИзИнтернет(), анализируя параметры получем метод GET, проверка в коде на "ПустаяСтрока(РезультатПроверки.ИмяОшибки)", значит анализируется только код ответа 200. Дополняем описание.

paths:
  /programs/update/ping:
    description: Проверка доступности сервиса
    get:
      responses:
        '200':
          description: Успешный ответ

 

Получение информации о доступном обновлении конфигурации и платформы

Используется в функции ИнформацияОДоступномОбновленииВызовОперации() в которой указан метод "POST", тип данных "application/json", "ФорматОтвета = 1", структура данных запроса в функции InfoRequestJSON(), обработка ответа производится функцией ЗаполнитьИнформациюОбОбновленииИзInfoResonseИзJSON().

 
 Обработка формата тела ответа

 

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

 

В теле запроса импользуются Дополнительные параметры, получаемые в ИнтернетПоддержкаПользователей.ДополнительныеПараметрыВызоваОперацииСервиса()

Добавляем их в виде схемы и добавляем к ним пример, готовый JSON получаем при запуске отладки, просматриваем с помощью https://jsoneditoronline.org/ конвретируем в YAML используя сервис https://www.json2yaml.com/

 
 Схема доп параметров с примером данных

Подключаем к схеме запроса

 
  Схема запроса

Для сложного форматирования описания используется Markdown.

 

При обработкке используется функция ЗаполнитьИнформациюОбОбновленииКонфигурацииИзJSON() из которого можно получить подструктуру которую можно описать отдельным компонентом и переиспользовать его.

 
 Схема элемента ответа

 

 
 Схема тела ответа

 

Дополняем описание запроса

  /programs/update/info:
    description: Получение информации о доступном обновлении конфигурации и платформы
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InfoRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InfoResonse'

 

Результат можно посмотреть в репозитории (сслыка), прямая ссылка на файл (ссылка)

Создание коллекции для тестирования работы

Для тестирования использую Postman (ссылка).

Загружаем описание API

 
 Скриншоты

 

Формируем коллекцию с наименованием "1c_update_service"

 
 Скриншоты

 

Проверяем работу проверки доступности

 
 Скриншот

 

Проверяем работу получения информации об обновлениях

 
 Скриншот

 

При клике на "issues" [8] можно увидеть расхождения относительно описания API.

 
 Скриншот

 

Итог

С помощью бесплатных инструменов можно удобно документировать и использовать описание HTTP API в работе.

 

Благодарю за внимание.

См. также

Сайты и интернет-магазины WEB-интеграция Системный администратор Программист Пользователь Платформа 1С v8.3 Конфигурации 1cv8 1С:Управление торговлей 11 Автомобили, автосервисы Россия Управленческий учет Платные (руб)

Интеграционный модуль обмена между конфигурацией Альфа Авто 5 и Альфа Авто 6 и порталом AUTOCRM. Данный модуль универсален. Позволяет работать с несколькими обменами AUTOCRM разных брендов в одной информационной базе в ручном и автоматическом режиме.

36000 руб.

03.08.2020    18019    18    22    

17

Сайты и интернет-магазины Интеграция WEB-интеграция Платформа 1С v8.3 Конфигурации 1cv8 Управленческий учет Платные (руб)

Интеграция 1С и Битрикс 24. Разработка имеет двухстороннюю синхронизацию 1С и Bitrix24 задачами. Решение позволяет создавать пользователя в 1С из Битрикс24 и наоборот. Данная разработка технически подходит под все основные конфигурации линейки продуктов 1С:Предприятие 8.3 (платформа начиная с 8.3.23). При приобретении предоставляется 1 месяц бесплатных обновлений разработки. Доступна демо-версия продукта с подключением Вашего Битрикс24

7200 руб.

04.05.2021    20164    13    19    

18

WEB-интеграция 8.3.8 Конфигурации 1cv8 Автомобили, автосервисы Беларусь Украина Россия Казахстан Управленческий учет Платные (руб)

Расширение предназначено для конфигурации "1С:Предприятие 8. Управление Автотранспортом. ПРОФ". Функционал модуля: 1. Заполнение регистров сведений по подсистеме "Мониторинг", а именно: события по мониторингу, координаты по мониторингу, пробег и расход по мониторингу, текущее местоположение ТС по мониторингу 2. Заполнение путевого листа: пробег по мониторингу, время выезда/заезда, табличная часть ГСМ, места стоянок по геозонам. 3. Отчеты по данным загруженным в регистры сведений. 4. Предусмотрена автоматическая загрузка данных в фоновом режиме (условия работы данной загрузке читайте в описании товара) Модуль работает без включенной константы по настройкам мониторинга. Модуль формы предоставляется с открытым кодом, общий модуль защищен. Любой заинтересованный пользователь, имеет возможность скачать демо-версию расширения.

22656 руб.

25.05.2021    14562    42    8    

18

WEB-интеграция Программист Руководитель проекта Платформа 1С v8.3 Конфигурации 1cv8 1С:Франчайзи, автоматизация бизнеса Платные (руб)

Расширение значительно упрощает написание API на 1С. Веб программисты получают простой и понятный доступ к 1С. Описание API создаётся автоматически и представляется в виде удобном как для человека, так и для программной обработки.

24000 руб.

27.09.2024    1746    1    0    

3
Комментарии
Подписаться на ответы Инфостарт бот Сортировка: Древо развёрнутое
Свернуть все
1. Yashazz 4796 02.11.20 12:39 Сейчас в теме
Сильно, грамотно, полезно. Отличная публикация, всё чётко, структурированно и технично. Не то, что у меня в кучу навалено...
8. Bukaska 140 02.11.20 17:39 Сейчас в теме
9. Yashazz 4796 02.11.20 18:38 Сейчас в теме
(8) а я никогда не отрицал, что оформление моих поделок - так себе. Я в этом плане всегда преклонялся перед дизайном Пермитина, например.
2. malikov_pro 1325 02.11.20 12:52 Сейчас в теме
(1) От Вас зачин, от меня уточнение.

По описанию, напишите какие URL нужно детализировать для дальнейшего использования (например для тестирования локального аналога), в продолжении того что сейчас активно используете эту подсистему, будет возможность - уточню документацию.
По идее можно написать клиент по построению графа обновлений.

В целом по теме можем продолжить, разбирайте внутренний механизм, после буду уточнять отрисосывая его в UML.
3. Yashazz 4796 02.11.20 13:13 Сейчас в теме
(2) Под графом понимается кратчайший сценарий между релизами обновлений?
5. VVi3ard 52 02.11.20 16:32 Сейчас в теме
(2) Интересная статья, одно время описали наши сервисы в OpenApi 2.0 и в постмане, причём делали максимально подробно с заполнением секции shema, с использованием ссылок.
Начали писать тесты, но жестко обломались т.к. не понятно было как проверять главное для нас: Структуру ответа.

(в нашем случае структура JSON объектов очень сложная и многоуровневая и чаще всего ломается или сама структура, или появляются значения не подходящие под фильтры, чаще всего NULL вместо строки/числа/даты)

Т.е. сделать запрос/получить ответ и проверить поля ответа/статус/время это всё без проблем множество уроков, описаний, и даже в самом постмане много шаблонов. Я поискал, поспрашивал на форумах, даже писал вопрос разработчикам и никто не смог мне сказать как использовать shema из спецификации для валидации ответа. В самом постмане есть метод, но он требует на вход текст схемы, т.е. ему нельзя сказать, возьми из исходного описания схему и сверь по ней.

А у вас в статье есть "При клике на "issues" [8] можно увидеть расхождения относительно описания API." и это крайне интересно, получается это всегда было.

Я же правильно понимаю что это как раз валидация ответа по схеме которая описана в спецификации?
6. malikov_pro 1325 02.11.20 16:45 Сейчас в теме
(5)
Понимаю что это как раз валидация ответа по схеме которая описана в спецификации?

Понимаете правильно.
Описание объекта в OpenAPI архитектурно состыковано с описанием JSON Schema.

https://postman-quick-reference-guide.readthedocs.io/en/latest/schema-validation.html
Пример из Postman
const schema = {
    "type": "object",
    "properties": {
        "code": { "type": "string" }
    }
};


из YAML
    InfoResonse:
      type: object
      properties:
        errorName:
          description: ИмяОшибки
          type: string


Не все гладко, но работать можно
https://apisyouwonthate.com/blog/openapi-v31-and-json-schema-2019-09

Конвертер, который нашелся с ходу
https://github.com/mikunn/openapi-schema-to-json-schema

Можно переиспользовать в 1С на уровне валидатора
https://infostart.ru/public/1265429/
10. VVi3ard 52 03.11.20 10:24 Сейчас в теме
(6)
В вашем примере как раз то что я находил, использование:
const schema = {
"type": "object"
};
And here is the test:

pm.test("Validate schema", () => {
pm.response.to.have.jsonSchema(schema);
});

Тут нужно описать схему, я же не понимаю почему я должен отдельно еще раз её описывать если я уже описал её в спецификации. Это хорошо когда схема такая простая как в примере а если там 40 полей, и часть из них описана через ссылки?

т.е. поменялась у нас схема, мы идем правим спецификацию и отдельно правим все тесты которые на неё завязаны.

То что вы описали это валидация по схеме но не по схеме из спецификации а по схеме определённой в тесте.

Я же подумал что postman научился приимпорте спецификации импортировать так же и схемы и автоматически их использовать при выполнении запроса (анализе результата запроса)..
4. malikov_pro 1325 02.11.20 13:28 Сейчас в теме
(3) В целом граф, дальше пользуйте как хотите, до этого в https://infostart.ru/public/633646/ данные брали со страницы ИТС, сейчас можно из public API взять.
По нахождению кратчайшего втречал в статье по разузлованию, но комментарий "Всегда ли кратчайший путь лучший? Я бы добавил отдельную опцию, чтобы переходы типа 2.0.*.* -> 2.1.*.* происходили с последнего из 2.0.*.*, например." актуален.
12. Ibrogim 1321 07.09.21 09:10 Сейчас в теме
(4) Делал в своё время (https://infostart.ru/1c/articles/385143/) поиск кратчайшего пути обновлений снизу и с верху, на сайте регулируется чекбоксом "Прямой/обратный обход релизов"
Оказалось, что результат может отличаться )
7. malikov_pro 1325 02.11.20 16:51 Сейчас в теме
(5) При использовании RAML в https://atom.io/packages/api-workbench у меня валидатор схемы ругается на несоответствие паттерну строки значения в примере к структуре. С точки зрения модели оно нормально связано, с точки зрения инструментов не все гладко.
11. malikov_pro 1325 03.11.20 11:35 Сейчас в теме
(10) Проблема понятна. Нужно учитывать что описание API не равняется тест-плану.

"т.е. поменялась у нас схема, мы идем правим спецификацию и отдельно правим все тесты которые на неё завязаны."
Если рассматриваем аспект проверки ответов на соответствие схеме то при применении Postman
1. Нет указания в коллекции ссылки к API, только обратная связь, проверяется после выполнения запроса не попадает в лог.
2. Схемы в OpenAPI как объекты в Postman это часть кода плана тестирования поэтому нужно их переносить скриптом, который
* разбирает коллекцию (JSON файл), выделяет из нее блоки,
* получает полные объекты из схемы, пример давал
* заполняет / дополняет код в элементе коллекции

Думаю более продвинутые инструменты для тестирования от описания есть, нужно дополнительно разбираться со списком https://openapi.tools/
Оставьте свое сообщение