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

Вводные

• БСП 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().

Если ПараметрыПолучения.ФорматОтвета = 0 Тогда
	Результат.Содержимое = Ответ.ПолучитьИмяФайлаТела();
ИначеЕсли ПараметрыПолучения.ФорматОтвета = 1 Тогда
	Результат.Содержимое = Ответ.ПолучитьТелоКакСтроку();
ИначеЕсли ПараметрыПолучения.ФорматОтвета = 2 Тогда
	Результат.Содержимое = Ответ.ПолучитьТелоКакДвоичныеДанные();
Иначе
	Результат.Содержимое = Ответ;
КонецЕсли;

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

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

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

  schemas:
    additionalParameters:
      type: object
      properties:
        key:
          description: Ключ
          type: string
        value:
          description: Значение
          type: string
      example:
        - key: ConfigLanguage
          value: ru
        - key: Vendor
          value: Фирма "1С"
        - key: ClientPlatformType
          value: Windows_x86
        - key: ConfigName
          value: БиблиотекаСтандартныхПодсистемДемо
        - key: ClientOSVersion
          value: Microsoft Windows 10 version 10.0  (Build 19041)
        - key: ConfigMainLanguage
          value: ru
        - key: LibraryVersion
          value: 2.4.1.36
        - key: PlatformVersion
          value: 8.3.17.1549
        - key: ConfigVersion
          value: 3.1.3.317
        - key: IBID
          value: 9ef71e24-e109-4e63-b12c-8af41928d659
        - key: CurLocalizationCode
          value: ru
        - key: SystemLanguage
          value: ru
        - key: ClientTimeOffsetGMT
          value: '18000'
        - key: countryId
          value: ''
        - key: IBIsSeparated
          value: 'false'
        - key: IBUserName
          value: Администратор
        - key: DomainZone
          value: ru

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

InfoRequest:
      type: object
      properties:
        programName:
          description: Имя текущей программы
          type: string
          example: "SSL"
        versionNumber:
          description: Версия текущей программы
          type: string
          example: "3.1.3.317"
        platformVersion:
          description: Текущая версия платформы 1С Предприятие
          type: string
          example: "8.3.17.1549"
        programNewName:
          description: Имя новой программы
          type: string  
        redactionNumber:
          description: Номер редакции новой программы
          type: string
        updateType:
          description: >
            СценарийОбновления:
              * `NewConfigurationAndOrPlatform` - РабочееОбновление
              * `NewProgramOrRedaction` - ПереходНаДругуюПрограммуИлиРедакцию
              * `NewPlatform`- Новая платформа
          type: string
          enum:
            - "NewConfigurationAndOrPlatform"
            - "NewProgramOrRedaction"
            - "NewPlatform"
        additionalParameters:
            $ref: '#/components/schemas/additionalParameters'

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

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

components:
  schemas: 
    UpdateConfigurationItem:
      type: object
      properties:
        configurationVersion:
          description: Версия
          type: string
        size:
          description: Размер обновления
          type: string
        updateInfoUrl:
          description: URL новое в версии
          type: string
        howToUpdateInfoUrl:
          description: URL порядок обновления
          type: string
        programVersionUin:
          description: Идентификатор версии
          type: string
        upgradeSequence:
          description: Файлы для загрузки
          type: array
          items: 
            type: string

components:
  schemas: 
    InfoResonse:
      type: object
      properties:
        errorName:
          description: ИмяОшибки
          type: string
        errorMessage:
          description: ИнформацияОбОшибке
          type: string
        configurationUpdateResponse:
          description: Информация об обновлении конфигурации
          type: array
          items: 
            $ref: '#/components/schemas/UpdateConfigurationItem'
        platformUpdateResponse:
          description: Информация об обновлении платформы
          type: array
          items: 
            $ref: '#/components/schemas/UpdateConfigurationItem'

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

  /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 в работе.

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