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

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

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

В наличии

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

Категория:

Описание

Вводные

  • БСП 3.1.3.17
  • Желание разобраться в механизме автоматического получения патчей и обновления типовых конфигураций
  • Статья с началом разбора темы //sale.itcity.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().

 

has been added to your cart:
Оформление заказа