# ─────────────────────────────────────────────────────────────────────────────
# Template — OpenAPI 3.1 spec para WxO
#
# Importar con:
#   orchestrate tools import -k openapi -f este_archivo.yaml --app-id mi_app
#
# REQUISITOS (paga con dolor):
# - description per-operation (issue I-005)
# - security per-operation, NO solo global (issue I-006)
# - servers[0].url parcheado en deploy time según env
# - Si el backend usa FastAPI, mejor exponer un endpoint /orchestrate-tools-spec.json
#   que filtra dinámicamente. Ver _backend_filter_endpoint.py.
# ─────────────────────────────────────────────────────────────────────────────

openapi: 3.1.0
info:
  title: "REPLACE Service API (orchestrate-exposed subset)"
  version: "1.0.0"
  description: "Subset filtrado de la API expuesto a WxO."

servers:
  # PATCH ME en deploy time:
  #   jq --arg url "$BACKEND_URL" '.servers = [{"url": $url}]'
  - url: "https://CHANGEME/api/v1"

# Security definitions (NO heredan a las ops — issue I-006)
components:
  securitySchemes:
    OrchestrateToken:
      type: apiKey
      in: header
      name: X-Orchestrate-Token        # custom header, NO Bearer (regla C2)

  schemas:
    RunCaseInput:
      type: object
      required: [case_id, target_id]
      properties:
        case_id:
          type: string
          description: "ID del caso a procesar."
        target_id:
          type: integer
          description: "ID del recurso objetivo."
        options:
          type: array
          items: { type: string }
          description: "Opciones adicionales."

    RunCaseResult:
      type: object
      properties:
        ok:        { type: boolean }
        ticket_id: { type: string }
        package_url: { type: string }
        error:     { type: string, nullable: true }

paths:
  /cases/run:
    post:
      operationId: run_full_case
      summary: "Run a case end-to-end"
      # description OBLIGATORIO — issue I-005
      description: |
        Procesa un caso completo invocando los substeps en el backend.
        Devuelve ok=true + ticket_id + package_url, o ok=false + error.
        Cada substep emite write_audit con case_id.
      security:                       # per-operation — issue I-006
        - OrchestrateToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/RunCaseInput" }
      responses:
        "200":
          description: "Resultado del procesamiento."
          content:
            application/json:
              schema: { $ref: "#/components/schemas/RunCaseResult" }