Анализ 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 в работе.

 

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

См. также

Интеграция Альфа Авто 5 / Альфа Авто 6 и AUTOCRM / Инфотек

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

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

36000 руб.

03.08.2020    15745    10    17    

11

Интеграция 1С — Битрикс24. Обмен задачами

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

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

5040 руб.

04.05.2021    17548    6    15    

13

Интеграция с сервисом vetmanager

WEB-интеграция Платформа 1С v8.3 Бухгалтерский учет 1С:Бухгалтерия 3.0 Бытовые услуги, сервис Платные (руб)

Внешняя обработка разрабатывалась для загрузки документов из Ветменеджер в 1С: Бухгалтерия 3.0

12000 руб.

02.02.2021    16359    42    49    

23

[Расширение] БОР-Навигатор.Культура

Зарплата Бюджетный учет WEB-интеграция Обмен с ГосИС Платформа 1С v8.3 Сложные периодические расчеты 1С:Зарплата и кадры государственного учреждения 3 Государственные, бюджетные структуры Россия Бюджетный учет Платные (руб)

Расширение конфигурации, включающее в себя объекты, необходимые для подготовки и сдачи отчета "Штатная численность" системы "БОР-Навигатор.Культура" в программе "1С:Зарплата и кадры государственного учреждения", редакция 3.1.

8400 руб.

01.02.2019    25741    9    0    

7

Заполнение по ИНН или наименованию реквизитов контрагента по данным сайта ФНС

Обмен с ГосИС WEB-интеграция Платформа 1С v8.3 Управляемые формы 1С:Комплексная автоматизация 1.х 1С:Бухгалтерия 2.0 1С:Управление торговлей 10 1С:Управление производственным предприятием 1С:Управление нашей фирмой 1.6 1С:Бухгалтерия государственного учреждения 1С:Документооборот 1С:ERP Управление предприятием 2 1С:Бухгалтерия 3.0 1С:Управление торговлей 11 1С:Комплексная автоматизация 2.х Платные (руб)

Обработка является альтернативой механизму, разработанному фирмой 1С и заполняющему реквизиты контрагента по ИНН или наименованию. Не требуется действующей подписки ИТС. Вызывается как внешняя дополнительная обработка, т.е. используется, непосредственно, из карточки контрагента. Заполнение по ИНН или наименованию реквизитов контрагента по данным сайта ФНС (egrul.nalog.ru) для БП 2.0, БП 3.0, БГУ 1.0, БГУ 2.0, УТ 10.3, УТ 11.x, КА 1.1, КА 2.x, УПП 1.x, ERP 2.x, УНФ 1.5, УНФ 1.6, УНФ 3.0, ДО 2.1

2400 руб.

28.04.2016    88579    160    215    

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

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

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

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

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