openapi: 3.1.0
info:
  title: DYO.gg API — Root Manifest
  version: 1.0.0
  summary: Multi-game data API (Genshin Impact / Honkai Star Rail / Zenless Zone Zero).
  description: |
    DYO.gg REST API v1 — spec dipecah per game dan resource internal.
    Untuk spec detail lihat:
      - /openapi/genshin.yaml
      - /openapi/hsr.yaml
      - /openapi/zzz.yaml
      - /openapi/internal.yaml
  termsOfService: https://dyogg.com/terms
  contact:
    name: DYO.gg Developer Team
    email: support@dyogg.com
    url: https://dyogg.com/docs
  license:
    name: MIT (spec) — data license see terms
    identifier: MIT
servers:
  - url: https://api.dyogg.com
    description: Production
  - url: https://api-staging.dyogg.com
    description: Staging (dyo_test_* keys only)
security:
  - bearerAuth: []
tags:
  - name: Player
    description: Player overview + showcase karakter lintas game.
  - name: Character
    description: Metadata karakter (avatar / trailblazer / agent).
  - name: Weapon
    description: Weapon / light cone / w-engine.
  - name: Artifact
    description: Artifact / relic / drive disc set.
  - name: Archive
    description: Notice, banner, event history.
  - name: Assets
    description: Signed URL asset R2.
  - name: TrustScore
    description: Skor komunitas per UID.
  - name: ScamReport
    description: Laporan scam komunitas.
  - name: BuildAnalyzer
    description: Analisis skor build karakter.
  - name: DamageCalculator
    description: Simulasi damage rotation.
  - name: Leaderboard
    description: Global ranking per karakter.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: DYO API Key (dyo_live_… / dyo_test_…)
  schemas:
    Meta:
      type: object
      required: [request_id, api_version, server_time]
      properties:
        cache:
          type: string
          enum: [hit, miss, stale]
        ttl_seconds:
          type: integer
        request_id:
          type: string
          example: req_01H8YZABC
        api_version:
          type: string
          enum: [v1, v2]
        server_time:
          type: string
          format: date-time
    Error:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          example: player_not_found
        message:
          type: string
        field:
          type: string
          nullable: true
        docs_url:
          type: string
          format: uri
    ErrorResponse:
      type: object
      required: [error, meta]
      properties:
        error:
          $ref: '#/components/schemas/Error'
        meta:
          $ref: '#/components/schemas/Meta'
    Game:
      type: string
      enum: [genshin, hsr, zzz]
    UID:
      type: string
      pattern: '^[0-9]{9,10}$'
      example: '816973814'
paths:
  /v1/games:
    get:
      tags: [Player]
      summary: List supported games
      description: Balikkan daftar game aktif + status endpoint.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: string }
                        status: { type: string, enum: [active, beta, soon] }
                  meta: { $ref: '#/components/schemas/Meta' }