{
  "openapi": "3.0.3",
  "info": {
    "title": "Ski Resort API",
    "version": "1.0.0",
    "description": "REST API for ski resort operations and mountain conditions."
  },
  "servers": [
    {
      "url": "http://localhost:4000",
      "description": "Local development"
    }
  ],
  "tags": [
    { "name": "Health" },
    { "name": "Sync" },
    { "name": "Resorts" },
    { "name": "Conditions" },
    { "name": "Insights" }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": ["Health"],
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "Service health",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "service": { "type": "string", "example": "ski-resort-api" },
                    "timestamp": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/sync/status": {
      "get": {
        "tags": ["Sync"],
        "summary": "Current sync service status",
        "responses": {
          "200": { "description": "Sync status" }
        }
      }
    },
    "/api/sync/run": {
      "post": {
        "tags": ["Sync"],
        "summary": "Trigger a sync run",
        "responses": {
          "200": { "description": "Updated sync status" }
        }
      }
    },
    "/api/sync/history": {
      "get": {
        "tags": ["Sync"],
        "summary": "Recent sync history",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "default": 20 }
          }
        ],
        "responses": {
          "200": { "description": "Sync history list" },
          "400": { "description": "Invalid limit" }
        }
      }
    },
    "/api/resorts": {
      "get": {
        "tags": ["Resorts"],
        "summary": "List resorts with filters",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "country", "in": "query", "schema": { "type": "string" } },
          { "name": "region", "in": "query", "schema": { "type": "string" } },
          { "name": "continent", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }
        ],
        "responses": {
          "200": { "description": "Resort list" },
          "400": { "description": "Invalid query" }
        }
      }
    },
    "/api/resorts/{id}": {
      "get": {
        "tags": ["Resorts"],
        "summary": "Get resort by id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Resort details" },
          "404": { "description": "Resort not found" }
        }
      }
    },
    "/api/resorts/{id}/weather": {
      "get": {
        "tags": ["Resorts"],
        "summary": "Get resort weather",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Weather details" },
          "404": { "description": "Resort not found" }
        }
      }
    },
    "/api/resorts/{id}/history": {
      "get": {
        "tags": ["Resorts"],
        "summary": "Get historical weather baseline and deviations",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "days",
            "in": "query",
            "schema": { "type": "integer", "minimum": 7, "maximum": 90, "default": 30 }
          },
          {
            "name": "years",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 }
          },
          {
            "name": "radiusKm",
            "in": "query",
            "schema": { "type": "number", "minimum": 1, "maximum": 40, "default": 12 }
          }
        ],
        "responses": {
          "200": { "description": "Historical baseline and deviations" },
          "400": { "description": "Invalid query" },
          "404": { "description": "Resort not found" },
          "502": { "description": "Provider lookup error" }
        }
      }
    },
    "/api/resorts/{id}/trails": {
      "get": {
        "tags": ["Resorts"],
        "summary": "Get resort trails",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Trails details" },
          "404": { "description": "Resort not found" }
        }
      }
    },
    "/api/resorts/{id}/lifts": {
      "get": {
        "tags": ["Resorts"],
        "summary": "Get resort lifts",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Lifts details" },
          "404": { "description": "Resort not found" }
        }
      }
    },
    "/api/resorts/{id}/compare": {
      "get": {
        "tags": ["Resorts"],
        "summary": "Compare two resorts",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "with",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "Comparison result" },
          "400": { "description": "Invalid query" },
          "404": { "description": "Resort not found" }
        }
      }
    },
    "/api/conditions/top-snow": {
      "get": {
        "tags": ["Conditions"],
        "summary": "Top snowfall resorts",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 50 }
          }
        ],
        "responses": {
          "200": { "description": "Top-snow list" },
          "400": { "description": "Invalid query" }
        }
      }
    },
    "/api/conditions/open-now": {
      "get": {
        "tags": ["Conditions"],
        "summary": "Open-now resorts",
        "parameters": [
          {
            "name": "minOpenTrailsPct",
            "in": "query",
            "schema": { "type": "number", "minimum": 0, "maximum": 100 }
          }
        ],
        "responses": {
          "200": { "description": "Open-now list" },
          "400": { "description": "Invalid query" }
        }
      }
    },
    "/api/conditions/storm-watch": {
      "get": {
        "tags": ["Conditions"],
        "summary": "Storm warning resorts",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 50 }
          }
        ],
        "responses": {
          "200": { "description": "Storm watch list" },
          "400": { "description": "Invalid query" }
        }
      }
    },
    "/api/insights/snow": {
      "get": {
        "tags": ["Insights"],
        "summary": "Snow insights",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 60, "default": 7 }
          }
        ],
        "responses": {
          "200": { "description": "Insights payload" },
          "400": { "description": "Invalid query" }
        }
      }
    }
  }
}