codeword/docs/openapi.yaml

openapi: 3.0.0
info:
  title: Codeword Recovery Service API
  version: 1.0.0
  description: API for handling password recovery for the Codeword service.


paths:
  /liveness:
    get:
      summary: Роут проверки активности
      responses:
        '200':
          description: Успех – сервис запущен

  /readiness:
    get:
      summary: Роут проверки базы данных
      responses:
        '200':
          description: Успех — сервис готов и соединение с БД живо
        '503':
          description: Служба недоступна — не удалось выполнить проверку связи с БД

  /recover:
    post:
      summary: Запустите процесс восстановления пароля
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Электронная почта, на которую нужно отправить инструкции по восстановлению
                Referrer:
                  type: string
                  description: URL-адрес referral, если он доступен
                RedirectionURL:
                  type: string
                  description: URL-адрес, на который перенаправляется пользователь после отправки электронного письма

      responses:
        '200':
          description: Запрос на восстановление принят, и возвращен идентификатор записи восстановления
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: Идентификатор запроса на восстановление
        '404':
          description: Пользователь не найден по электронной почте
        '500':
          description: Внутренняя ошибка сервера – разные причины

  /recover/{sign}:
    get:
      summary: Обработать ссылку восстановления, в которой содержится подпись и обменять ее на токены
      parameters:
        - in: path
          name: sign
          required: true
          schema:
            type: string
          description: Подпись восстановления как часть URL-адреса восстановления
      responses:
        '200':
          description: Восстановление успешно, информация для обмена токенов возвращена
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken:
                    type: string
                  refreshToken:
                    type: string
        '406':
          description: NotAcceptable - срок действия ссылки для восстановления истек или она недействительна
        '500':
          description: Внутренняя ошибка сервера – разные причины

  /promocode/create:
    post:
      summary: Создать новый промокод
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromoCodeRequest'
      responses:
        '201':
          description: Новый промокод успешно создан
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCodeResponse'
        '400':
          description: Invalid request payload / Duplicate Codeword
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string

  /promocode/edit:
    put:
      summary: Обновить существующий промокод
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReqEditPromoCode'
      responses:
        '200':
          description: Промокод успешно обновлен
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromoCodeResponse'
        '400':
          description: Неверный формат запроса
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '404':
          description: Промокод не найден
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '500':
          description: Внутренняя ошибка сервера
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string


components:
  schemas:
    PromoCodeRequest:
      type: object
      properties:
        codeword:
          type: string
          description: Кодовое слово, которое должен ввести пользователь
        description:
          type: string
          description: Описание, необходимое для администратора в панели управления
        greetings:
          type: string
          description: Текст, который будет отправлен пользователю в ответ на активацию кода
        dueTo:
          type: integer
          format: int64
          description: Временная метка окончания активации кода
        activationCount:
          type: integer
          format: int64
          description: Лимит активации кода
        bonus:
          type: object
          properties:
            privilege:
              type: object
              properties:
                privilegeID:
                  type: string
                  description: Идентификатор привилегии, которую необходимо предоставить
                amount:
                  type: integer
                  format: uint64
                  description: Размер привилегии
            discount:
              type: object
              properties:
                layer:
                  type: integer
                factor:
                  type: number
                target:
                  type: string
                threshold:
                  type: integer
          description: Информация о бонусах
        outdated:
          type: boolean
        offLimit:
          type: boolean
        delete:
          type: boolean

    PromoCodeResponse:
      type: object
      properties:
        id:
          type: string
          description: ID созданного промокода
        codeword:
          type: string
          description: Кодовое слово промокода
        description:
          type: string
          description: Описание промокода
        greetings:
          type: string
          description: Текст, который будет отправлен пользователю в ответ на активацию кода
        dueTo:
          type: integer
          format: int64
          description: Временная метка окончания активации кода
        activationCount:
          type: integer
          format: int64
          description: Лимит активации кода
        bonus:
          type: object
          properties:
            privilege:
              type: object
              properties:
                privilegeID:
                  type: string
                  description: Идентификатор привилегии, которую необходимо предоставить
                amount:
                  type: integer
                  format: uint64
                  description: Размер привилегии
            discount:
              type: object
              properties:
                layer:
                  type: integer
                factor:
                  type: number
                target:
                  type: string
                threshold:
                  type: integer
          description: Информация о бонусах
        outdated:
          type: boolean
        offLimit:
          type: boolean
        delete:
          type: boolean
        createdAt:
          type: string
          format: date-time
          description: Время создания промокода

    ReqEditPromoCode:
      type: object
      properties:
        id:
          type: string
          description: ID промокода, который обновляем
        description:
          type: string
          description: Описание, необходимое менеджеру в админке
        greetings:
          type: string
          description: Текст, выдаваемый пользователю в ответ на активацию промокода
        dueTo:
          type: integer
          format: int64
          description: Временная метка окончания активации кода
        activationCount:
          type: integer
          format: int64
          description: Предел количества активаций промокода
        delete:
          type: boolean
          description: Флаг удаления промокода
      required:
        - id