API Сервиса обработки данных с ТСД

popolochkam-dct-openapi.yaml

openapi: 3.0.0

servers:
  - description: Тестовый сервис
    url: https://pre.tsd.po-polochkam.ru
    
info:
  title: Сервис обработки данных с ТСД
  description: |
    Сервис предназначен для извлечения данных о товарах из фотографий экранов
    терминалов сбора данных (ТСД).
    
    С экрана ТСД считывается ряд фактов о товаре. Список считываемых фактов с их
    описанием можно получить через API.
    
    Для обработки сервис через API принимает задание со ссылкой на фотографию.
    Перед выполнением задания он отдает клиенту ответ об успешном получении
    задания и после этого приступает к обработке.
    
    Результаты обработки сервис отправляет на указанный в конфигурации сервиса
    URL в виде HTTP-запроса методом **POST** с типом содержимого
    **application/json**. Формат ответа см. ниже в описании структуры
    [Результат обработки изображения](#model-TaskResult).
  version: "1.0.0"

paths:
  /recognition:
    post:
      tags: ['API сервиса']
      summary: Постановка задачи на обработку
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '202':
          description: Успешная постановка задачи на обработку
        '400':
          description: Ошибка структуры или валидности данных запроса
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    title: Текст ошибки для программиста, использующего API
                    type: string
                    example:
                      Невозможно получить изображение для обработки.
                      image_url должен содержать адрес публично-доступного
                      изображения
        '429':
          description:
            Сервис занят обработкой полученных ранее задач и не готов принять
            новую задачу на обработку. Следует повторить попытку позже
        '500':
          description:
            Внутренняя ошибка сервера, возникшая в процессе постановки задачи
            на обработку
  /facts:
    get:
      tags: ['API сервиса']
      summary: Получение списка выделяемых из изображений фактов
      responses:
        '200':
          description: Список выделяемых из изображений фактов
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                      code:
                        type: string
                        example: promo
                      description:
                        type: string
                        example: Товар участвует в промоакции
              example:
                - code: promo
                  description: Товар участвует в промоакции
                - code: assortment
                  description: Товар в ассортименте
                - code: in_stock
                  description: Товар имеется в наличии
        '500':
          description:
            Внутренняя ошибка сервера, возникшая в процессе получения списка фактов
components:
  schemas:
    Task:
      title: Задача на обработку изображения
      type: object
      required:
        - request_id
        - image_url
      properties:
        request_id:
          title:
            Произвольная строка по которой будет идентифицирован
            результат обработки задания
          type: string
          example: e92f7ae9-6c4c-4e9d-945f-0c65c742c29a
        image_url:
          title: URL на файл фотографии экрана ТСД
          type: string
          format: url
          example: https://files.po-polochkam.ru/GB/VI7XYdcbJmU7He.jpg
    TaskResult:
      title: Результат обработки изображения
      oneOf:
        - title: Успешная обработка изображения
          type: object
          required:
            - request_id
            - result
            - facts
          properties:
            request_id:
              description:
                Идентификатор задания на обработку, пришедший в запросе
                на обработку
              type: string
            result:
              description:
                Код результата выполнения задачи
              type: string
              example: success
            facts:
              description: Список фактов, полученных из изображения
              type: array
              items:
                oneOf:
                  - description: Товар участвует в промоакции
                    required:
                      - code
                      - value
                    properties:
                      code:
                        type: string
                        example: promo
                      value:
                        type: string
                        example: 'yes'
                        enum: ['yes', 'no', 'not found']
                  - description: Товар в ассортименте
                    required:
                      - code
                      - value
                    properties:
                      code:
                        type: string
                        example: assortment
                      value:
                        type: string
                        example: 'no'
                        enum: ['yes', 'no', 'not found']
                  - description: Товар имеется в наличии
                    required:
                      - code
                      - value
                    properties:
                      code:
                        type: string
                        example: in_stock
                      value:
                        type: string
                        example: 'not found'
                        enum: ['yes', 'no', 'not found']
        - title: Ошибка при обработке изображения
          type: object
          required:
            - request_id
            - result
            - error_code
            - error_message
          properties:
            request_id:
              description:
                Идентификатор задания на обработку, пришедший в запросе
                на обработку
              type: string
            result:
              description:
                Код результата выполнения задачи
              type: string
              example: failure
            error_code:
              description: Код ошибки обработки
              type: string
              enum: ['unclassified']
            error_message:
              description: Текст ошибки для программиста, использующего API
              type: string
              example:
                Неизвестная ошибка обработки