openapi: 3.0.3
info:
  title: Pipu Music API
  version: 0.1.0
  description: |
    Публичный REST API Pipu Music. Источник истины для сервера (oapi-codegen)
    и клиентов (openapi-typescript). Соглашения — docs/api.md.
servers:
  - url: /
tags:
  - name: system
paths:
  /healthz:
    get:
      operationId: getHealthz
      tags: [system]
      summary: Живость процесса
      responses:
        "200":
          description: Процесс жив
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthStatus"
  /readyz:
    get:
      operationId: getReadyz
      tags: [system]
      summary: Готовность обслуживать запросы (зависимости доступны)
      responses:
        "200":
          description: Все зависимости доступны
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReadyStatus"
        "503":
          description: Одна или несколько зависимостей недоступны
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReadyStatus"
  /api/v1/server-info:
    get:
      operationId: getServerInfo
      tags: [system]
      summary: Сведения о сервере для клиентов
      description: |
        Вызывается без аутентификации: веб и Android проверяют версию сервера,
        совместимость клиента и поддерживаемые языки (экран подключения).
      responses:
        "200":
          description: Сведения о сервере
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerInfo"
        default:
          $ref: "#/components/responses/Problem"
components:
  responses:
    Problem:
      description: Ошибка (RFC 9457)
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
  schemas:
    HealthStatus:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [ok]
    ReadyStatus:
      type: object
      required: [status, checks]
      properties:
        status:
          type: string
          enum: [ok, degraded]
        checks:
          type: object
          description: Результат проверки каждой зависимости
          additionalProperties:
            type: string
            description: "`ok` или текст ошибки"
    ServerInfo:
      type: object
      required: [name, version, api_version, supported_locales, min_android_version_code]
      properties:
        name:
          type: string
          example: pipu-music
        version:
          type: string
          description: Версия сервера (SemVer)
          example: 0.1.0
        api_version:
          type: string
          example: v1
        supported_locales:
          type: array
          items:
            type: string
          example: [ru, en]
        min_android_version_code:
          type: integer
          description: Минимальный versionCode Android-приложения, которое поддерживает сервер
          example: 10099
    Problem:
      type: object
      required: [status, code]
      properties:
        type:
          type: string
          default: about:blank
        status:
          type: integer
        code:
          type: string
          description: Машинный код ошибки для i18n, например `auth.invalid_credentials`
        detail:
          type: string
          description: Пояснение для логов (не для показа пользователю)
        params:
          type: object
          additionalProperties: true