openapi.yaml

openapi: 3.1.1
info:
  title: ITB Auctions API
  description: API для управления аукционами и лотами
  contact:
    name: ITB Team
    email: support@itb.com
  version: 1.0.0
servers:
  - url: https://api.itbrz.ru
tags:
  - name: Auctions
    description: Методы для работы с аукционами и лотами
paths:
  /lot:
    post:
      tags:
        - Auctions
      summary: Создание нового лота
      description: Создаёт новый лот для аукциона или фиксированного предложения.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lot_body'
        required: true
      responses:
        '200':
          description: Лот успешно создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200'
  /lot/{lotId}/bid:
    post:
      tags:
        - Auctions
      summary: Сделать ставку на лот
      description: Позволяет пользователю сделать ставку на лот.
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lotId_bid_body'
        required: true
      responses:
        '200':
          description: Ставка успешно сделана
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_1'
  /lot/{lotId}/end:
    post:
      tags:
        - Auctions
      summary: Завершение лота
      description:
        "Завершаем аукцион или фиксированное предложение, определяем по\
        бедителя."
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: 'Лот завершён, победитель определён'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_2'
  /lots/active:
    get:
      tags:
        - Auctions
      summary: Получить все активные лоты
      description: 'Получить список всех активных лотов, которые ещё не завершены.'
      responses:
        '200':
          description: Список активных лотов
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_3'
  /lot/{lotId}:
    get:
      tags:
        - Auctions
      summary: Получить информацию о лоте
      description: 'Получить подробную информацию о лоте, включая историю ставок.'
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Подробная информация о лоте
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_4'
    put:
      tags:
        - Auctions
      summary: Изменение данных лота
      description:
        "Обновление информации о лоте, включая название, описание, став\
        ку и дату окончания."
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lot_lotId_body'
        required: true
      responses:
        '200':
          description: Лот успешно обновлён
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200'
    delete:
      tags:
        - Auctions
      summary: Удаление лота
      description: Удаляет лот из системы.
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Лот успешно удалён
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_5'
  /lot/{lotId}/activity:
    get:
      tags:
        - Auctions
      summary: Получить активность лота
      description:
        "Получить данные о взаимодействии с лотом (просмотры, ставки, п\
        росмотры пользователями)."
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Информация о активности
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_6'
  /lot/{lotId}/stats:
    get:
      tags:
        - Auctions
      summary: Статистика ставок на лот
      description:
        "Получить статистику по ставкам на конкретный лот (средняя став\
        ка, количество ставок и т.д.)."
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Статистика ставок
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_7'
  /lot/{lotId}/status:
    get:
      tags:
        - Auctions
      summary: Получить статус лота
      description:
        "Получить текущий статус лота (активен, завершён, отменён и т.д\
        .)."
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Статус лота
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_8'
  /lot/{lotId}/bids:
    get:
      tags:
        - Auctions
      summary: Получить все ставки на лот
      description: 'Получить список всех ставок, сделанных на определённый лот.'
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Список всех ставок на лот
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_9'
  /lot/{lotId}/bid/{bidId}:
    put:
      tags:
        - Auctions
      summary: Изменить ставку
      description: 'Обновление ставки на лот (например, повышение ставки).'
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: bidId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bid_bidId_body'
        required: true
      responses:
        '200':
          description: Ставка успешно обновлена
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_1'
    delete:
      tags:
        - Auctions
      summary: Отмена ставки
      description: Позволяет пользователю отменить свою ставку на лот.
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: bidId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Ставка успешно отменена
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_10'
  /lot/{lotId}/winner:
    get:
      tags:
        - Auctions
      summary: Получить информацию о победителе
      description: 'Получить информацию о пользователе, который выиграл лот.'
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Информация о победителе
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_11'
  /lot/{lotId}/notify:
    post:
      tags:
        - Auctions
      summary: Уведомления о новых ставках
      description:
        "Отправка уведомлений пользователям, когда на лот поступает нов\
        ая ставка."
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lotId_notify_body'
        required: true
      responses:
        '200':
          description: Уведомление успешно отправлено
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_12'
  /lot/{lotId}/notify-winner:
    post:
      tags:
        - Auctions
      summary: Уведомление победителя
      description:
        "Отправить уведомление пользователю, который победил в аукционе\
        ."
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lotId_notifywinner_body'
        required: true
      responses:
        '200':
          description: Уведомление успешно отправлено
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_12'
  /lot/{lotId}/report:
    get:
      tags:
        - Auctions
      summary: Отчёт по лоту
      description:
        "Получить отчёт о лоте, включая историю всех ставок, победителя\
        \ и цену."
      parameters:
        - name: lotId
          in: path
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Отчёт о лоте
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_13'
  /lots/search:
    get:
      tags:
        - Auctions
      summary: Поиск лотов
      description:
        "Поиск лотов по различным фильтрам (категория, ставка, дата око\
        нчания и т.д.)."
      parameters:
        - name: category
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: string
        - name: minBid
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: number
        - name: maxBid
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: number
        - name: endDateBefore
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: string
            format: date-time
        - name: endDateAfter
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Список найденных лотов
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200_14'
components:
  schemas:
    lot_body:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        startingBid:
          type: number
          description: Начальная ставка (если это аукцион)
        category:
          type: string
        endDate:
          type: string
          format: date-time
        isFixedPrice:
          type: boolean
    inline_response_200:
      type: object
      properties:
        lotId:
          type: string
        title:
          type: string
        description:
          type: string
        startingBid:
          type: number
        category:
          type: string
        endDate:
          type: string
          format: date-time
        isFixedPrice:
          type: boolean
    lotId_bid_body:
      type: object
      properties:
        bidAmount:
          type: number
    inline_response_200_1:
      type: object
      properties:
        bidId:
          type: string
        lotId:
          type: string
        bidAmount:
          type: number
        userId:
          type: string
        createdAt:
          type: string
          format: date-time
    inline_response_200_2:
      type: object
      properties:
        message:
          type: string
        lotId:
          type: string
        winningBid:
          type: object
          properties:
            bidAmount:
              type: number
            userId:
              type: string
            createdAt:
              type: string
              format: date-time
    inline_response_200_3:
      type: object
      properties:
        activeLots:
          type: array
          items:
            type: object
            properties:
              lotId:
                type: string
              title:
                type: string
              description:
                type: string
              startingBid:
                type: number
              category:
                type: string
              endDate:
                type: string
                format: date-time
              status:
                type: string
                enum:
                  - active
    inline_response_200_4:
      type: object
      properties:
        lotId:
          type: string
        title:
          type: string
        description:
          type: string
        startingBid:
          type: number
        category:
          type: string
        endDate:
          type: string
          format: date-time
        isFixedPrice:
          type: boolean
        status:
          type: string
        bids:
          type: array
          items:
            type: object
            properties:
              bidId:
                type: string
              bidAmount:
                type: number
              userId:
                type: string
              createdAt:
                type: string
                format: date-time
    lot_lotId_body:
      type: object
      properties:
        title:
          type: string
        description:
          type: string
        startingBid:
          type: number
        category:
          type: string
        endDate:
          type: string
          format: date-time
        isFixedPrice:
          type: boolean
    inline_response_200_5:
      type: object
      properties:
        message:
          type: string
        lotId:
          type: string
    inline_response_200_6:
      type: object
      properties:
        lotId:
          type: string
        views:
          type: integer
        bidCount:
          type: integer
        userBids:
          type: array
          items:
            type: object
            properties:
              userId:
                type: string
              bidAmount:
                type: number
              createdAt:
                type: string
                format: date-time
    inline_response_200_7:
      type: object
      properties:
        lotId:
          type: string
        totalBids:
          type: integer
        averageBidAmount:
          type: number
        highestBidAmount:
          type: number
        lowestBidAmount:
          type: number
    inline_response_200_8:
      type: object
      properties:
        lotId:
          type: string
        status:
          type: string
          enum:
            - active
            - ended
            - cancelled
    inline_response_200_9:
      type: object
      properties:
        lotId:
          type: string
        bids:
          type: array
          items:
            type: object
            properties:
              bidId:
                type: string
              bidAmount:
                type: number
              userId:
                type: string
              createdAt:
                type: string
                format: date-time
    bid_bidId_body:
      type: object
      properties:
        bidAmount:
          type: number
    inline_response_200_10:
      type: object
      properties:
        message:
          type: string
        lotId:
          type: string
        bidId:
          type: string
    inline_response_200_11:
      type: object
      properties:
        lotId:
          type: string
        winner:
          type: object
          properties:
            userId:
              type: string
            bidAmount:
              type: number
            createdAt:
              type: string
              format: date-time
    lotId_notify_body:
      type: object
      properties:
        userId:
          type: string
        message:
          type: string
    inline_response_200_12:
      type: object
      properties:
        message:
          type: string
        lotId:
          type: string
        userId:
          type: string
    lotId_notifywinner_body:
      type: object
      properties:
        userId:
          type: string
        message:
          type: string
    inline_response_200_13:
      type: object
      properties:
        lotId:
          type: string
        title:
          type: string
        description:
          type: string
        startingBid:
          type: number
        category:
          type: string
        endDate:
          type: string
          format: date-time
        winner:
          type: object
          properties:
            userId:
              type: string
            bidAmount:
              type: number
        bids:
          type: array
          items:
            type: object
            properties:
              bidId:
                type: string
              bidAmount:
                type: number
              userId:
                type: string
              createdAt:
                type: string
                format: date-time
    inline_response_200_14:
      type: object
      properties:
        lots:
          type: array
          items:
            type: object
            properties:
              lotId:
                type: string
              title:
                type: string
              description:
                type: string
              startingBid:
                type: number
              category:
                type: string
              endDate:
                type: string
                format: date-time
              status:
                type: string
                enum:
                  - active
                  - ended