openapi: "3.0.3"
info:
  title: MoexVibe API
  description: |
    API для анализа ценных бумаг Московской биржи.
    Backend является единственной точкой доступа к MOEX ISS.
  version: "1.0.0"
  contact:
    name: MoexVibe Team

servers:
  - url: http://localhost:3000/api/v1
    description: Local development
  - url: https://api.moexvibe.example.com/api/v1
    description: Production

paths:
  /health:
    get:
      operationId: healthCheck
      tags: [Health]
      summary: Проверка состояния сервиса
      responses:
        "200":
          description: Сервис работает
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"

  /securities/search:
    get:
      operationId: searchSecurities
      tags: [Securities]
      summary: Поиск по инструментам
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 100
          description: Поисковый запрос (тикер, название, ISIN)
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum: [all, share, bond]
            default: all
          description: Фильтр по типу инструмента
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Максимальное количество результатов
      responses:
        "200":
          description: Результаты поиска
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"
        "400":
          $ref: "#/components/responses/BadRequest"

  /securities/shares/{secid}:
    get:
      operationId: getShare
      tags: [Shares]
      summary: Получить спецификацию акции
      parameters:
        - name: secid
          in: path
          required: true
          schema:
            type: string
          description: SECID инструмента (e.g. SBER)
      responses:
        "200":
          description: Спецификация акции
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StockResponse"
        "404":
          $ref: "#/components/responses/NotFound"

  /securities/shares/{secid}/marketdata:
    get:
      operationId: getShareMarketData
      tags: [Shares]
      summary: Получить рыночные данные акции
      parameters:
        - name: secid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Рыночные данные
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StockMarketDataResponse"
        "404":
          $ref: "#/components/responses/NotFound"

  /securities/shares/{secid}/candles:
    get:
      operationId: getShareCandles
      tags: [Shares]
      summary: Получить свечи для графика цены акции
      parameters:
        - name: secid
          in: path
          required: true
          schema:
            type: string
        - name: interval
          in: query
          required: true
          schema:
            type: string
            enum: ["1h", "24h"]
          description: Таймфрейм свечей
        - name: from
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Начальная дата (ISO 8601)
        - name: till
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Конечная дата (ISO 8601)
      responses:
        "200":
          description: Массив свечей
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CandlesResponse"
        "400":
          $ref: "#/components/responses/BadRequest"

  /securities/shares/{secid}/history:
    get:
      operationId: getShareHistory
      tags: [Shares]
      summary: Получить дневную историю торгов акции
      parameters:
        - name: secid
          in: path
          required: true
          schema:
            type: string
        - name: from
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: till
          in: query
          required: true
          schema:
            type: string
            format: date
      responses:
        "200":
          description: Дневная история
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HistoryResponse"

  /securities/shares/{secid}/dividends:
    get:
      operationId: getShareDividends
      tags: [Shares]
      summary: Получить историю дивидендных выплат
      parameters:
        - name: secid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Дивиденды
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DividendsResponse"
        "404":
          $ref: "#/components/responses/NotFound"

  /securities/bonds/{secid}:
    get:
      operationId: getBond
      tags: [Bonds]
      summary: Получить спецификацию облигации
      parameters:
        - name: secid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Спецификация облигации
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BondResponse"
        "404":
          $ref: "#/components/responses/NotFound"

  /securities/bonds/{secid}/marketdata:
    get:
      operationId: getBondMarketData
      tags: [Bonds]
      summary: Получить рыночные данные облигации
      parameters:
        - name: secid
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Рыночные данные облигации
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BondMarketDataResponse"
        "404":
          $ref: "#/components/responses/NotFound"

  /securities/bonds/{secid}/candles:
    get:
      operationId: getBondCandles
      tags: [Bonds]
      summary: Получить свечи для графика цены облигации
      parameters:
        - name: secid
          in: path
          required: true
          schema:
            type: string
        - name: interval
          in: query
          required: true
          schema:
            type: string
            enum: ["1h", "24h"]
        - name: from
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: till
          in: query
          required: true
          schema:
            type: string
            format: date
      responses:
        "200":
          description: Массив свечей
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CandlesResponse"

  /securities/bonds/{secid}/history:
    get:
      operationId: getBondHistory
      tags: [Bonds]
      summary: Получить дневную историю торгов облигации
      parameters:
        - name: secid
          in: path
          required: true
          schema:
            type: string
        - name: from
          in: query
          required: true
          schema:
            type: string
            format: date
        - name: till
          in: query
          required: true
          schema:
            type: string
            format: date
      responses:
        "200":
          description: Дневная история
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BondHistoryResponse"

components:
  schemas:
    # ── Health ──
    HealthResponse:
      type: object
      properties:
        status:
          type: string
          example: "ok"
        timestamp:
          type: string
          format: date-time
        uptime:
          type: number
      required: [status, timestamp, uptime]

    # ── Api Response Wrapper ──
    ApiResponse:
      type: object
      properties:
        data: {}
        meta:
          type: object
          properties:
            cachedAt:
              type: string
              format: date-time
              nullable: true
            fromCache:
              type: boolean
      required: [data]

    # ── Search ──
    SearchResult:
      type: object
      properties:
        secid:
          type: string
          example: "SBER"
        isin:
          type: string
          example: "RU0009029540"
        shortName:
          type: string
          example: "Сбербанк"
        type:
          type: string
          enum: [share, bond]
        listLevel:
          type: integer
          example: 1
        currency:
          type: string
          nullable: true
          example: "RUB"
        price:
          type: number
          nullable: true
          example: 322.35
      required: [secid, isin, shortName, type, listLevel]

    SearchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/SearchResult"
        meta:
          $ref: "#/components/schemas/ApiResponse/properties/meta"

    # ── Stock ──
    StockMarketData:
      type: object
      properties:
        price:
          type: number
          example: 322.35
        change:
          type: number
          example: 1.15
        changePercent:
          type: number
          example: 0.36
        open:
          type: number
          example: 321.30
        high:
          type: number
          example: 322.66
        low:
          type: number
          nullable: true
          example: 321.20
        volume:
          type: integer
          example: 1925163
        value:
          type: number
          example: 620184479
        issueCapitalization:
          type: number
          example: 6958336818320
        updatedAt:
          type: string
          format: date-time
          example: "2026-06-13T18:03:11Z"
      required: [price, change, changePercent, open, volume, value, updatedAt]

    Stock:
      type: object
      properties:
        secid:
          type: string
          example: "SBER"
        isin:
          type: string
          example: "RU0009029540"
        name:
          type: string
          example: "Сбербанк России ПАО ао"
        shortName:
          type: string
          example: "Сбербанк"
        latName:
          type: string
          nullable: true
          example: "Sberbank"
        listLevel:
          type: integer
          example: 1
        issueSize:
          type: integer
          example: 21586948000
        faceValue:
          type: number
          example: 3
        faceUnit:
          type: string
          example: "RUB"
        type:
          type: string
          example: "common_share"
        marketData:
          $ref: "#/components/schemas/StockMarketData"
      required: [secid, isin, name, shortName, listLevel, type, marketData]

    StockResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/Stock"
        meta:
          $ref: "#/components/schemas/ApiResponse/properties/meta"

    StockMarketDataResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/StockMarketData"
        meta:
          $ref: "#/components/schemas/ApiResponse/properties/meta"

    # ── Bond ──
    BondMarketData:
      type: object
      properties:
        price:
          type: number
          example: 100.45
          description: Цена в % от номинала
        yieldToMaturity:
          type: number
          nullable: true
          example: 12.71
        yieldAtWaprice:
          type: number
          nullable: true
        duration:
          type: number
          nullable: true
        accruedInt:
          type: number
          example: 29.48
        couponValue:
          type: number
          example: 40.64
        couponPercent:
          type: number
          nullable: true
          example: 8.15
        nextCouponDate:
          type: string
          format: date
          nullable: true
          example: "2026-08-05"
        open:
          type: number
        high:
          type: number
          nullable: true
        low:
          type: number
          nullable: true
        volume:
          type: integer
        updatedAt:
          type: string
          format: date-time
      required: [price, accruedInt, couponValue, volume, updatedAt]

    Bond:
      type: object
      properties:
        secid:
          type: string
        isin:
          type: string
        name:
          type: string
        shortName:
          type: string
        latName:
          type: string
          nullable: true
        listLevel:
          type: integer
        issueSize:
          type: integer
        faceValue:
          type: number
        faceUnit:
          type: string
        matDate:
          type: string
          format: date
          example: "2027-02-03"
        couponValue:
          type: number
          example: 40.64
        couponPercent:
          type: number
          nullable: true
          example: 8.15
        couponPeriod:
          type: integer
          example: 182
        nextCoupon:
          type: string
          format: date
          example: "2026-08-05"
        accruedInt:
          type: number
          example: 29.48
        bondType:
          type: string
          example: "Фикс с известным купоном"
        bondSubType:
          type: string
          example: "До погашения"
        offerDate:
          type: string
          format: date
          nullable: true
        buybackDate:
          type: string
          format: date
          nullable: true
        marketData:
          $ref: "#/components/schemas/BondMarketData"
      required: [secid, isin, name, shortName, listLevel, matDate, couponValue,
                 couponPeriod, accruedInt, bondType, marketData]

    BondResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/Bond"
        meta:
          $ref: "#/components/schemas/ApiResponse/properties/meta"

    BondMarketDataResponse:
      type: object
      properties:
        data:
          $ref: "#/components/schemas/BondMarketData"
        meta:
          $ref: "#/components/schemas/ApiResponse/properties/meta"

    # ── Candle ──
    Candle:
      type: object
      properties:
        open:
          type: number
          example: 280.00
        high:
          type: number
          example: 280.41
        low:
          type: number
          example: 271.80
        close:
          type: number
          example: 272.25
        volume:
          type: integer
          example: 43086870
        value:
          type: number
          example: 11853565984.9
        begin:
          type: string
          format: date-time
          example: "2025-01-03T00:00:00Z"
        end:
          type: string
          format: date-time
          example: "2025-01-03T23:59:59Z"
      required: [open, high, low, close, volume, value, begin, end]

    CandlesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Candle"
        meta:
          $ref: "#/components/schemas/ApiResponse/properties/meta"

    # ── History ──
    HistoryEntry:
      type: object
      properties:
        date:
          type: string
          format: date
        open:
          type: number
        high:
          type: number
        low:
          type: number
        close:
          type: number
        volume:
          type: integer
        value:
          type: number
      required: [date, open, high, low, close, volume, value]

    HistoryResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/HistoryEntry"
        meta:
          $ref: "#/components/schemas/ApiResponse/properties/meta"

    BondHistoryEntry:
      type: object
      properties:
        date:
          type: string
          format: date
        closePrice:
          type: number
        yieldClose:
          type: number
          nullable: true
        duration:
          type: number
          nullable: true
      required: [date, closePrice]

    BondHistoryResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/BondHistoryEntry"
        meta:
          $ref: "#/components/schemas/ApiResponse/properties/meta"

    # ── Dividend ──
    Dividend:
      type: object
      properties:
        registryCloseDate:
          type: string
          format: date
          example: "2025-07-18"
        value:
          type: number
          example: 34.84
        currency:
          type: string
          example: "RUB"
      required: [registryCloseDate, value, currency]

    DividendsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Dividend"
        meta:
          $ref: "#/components/schemas/ApiResponse/properties/meta"

    # ── Error ──
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 404
        message:
          type: string
          example: "Instrument SBER_NOT_FOUND not found"
        error:
          type: string
          example: "Not Found"
        timestamp:
          type: string
          format: date-time
        path:
          type: string
          example: "/api/v1/securities/shares/SBER_NOT_FOUND"
      required: [statusCode, message, error, timestamp, path]

  responses:
    BadRequest:
      description: Неверный запрос
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: Инструмент не найден
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

tags:
  - name: Health
    description: Мониторинг состояния сервиса
  - name: Securities
    description: Поиск инструментов
  - name: Shares
    description: Акции
  - name: Bonds
    description: Облигации