# storage/api/openapi.yaml
openapi: 3.0.0
info:
  title: Weather Widget API
  description: API pour fournir des données météo aux opérateurs.
  version: 1.0.0
  contact:
    name: Support Technique
    email: support@themobileconcept.com

servers:
  - url: https://tmc.fr/api
    description: Environnement local
  - url: https://api.meteo-site.com/api
    description: Environnement de production

paths:
  /weather:
    get:
      summary: Récupère les données météo pour un partenaire
      description: |
        Retourne les données météo actuelles avec les URLs de tracking Google Analytics.
        La localisation est déterminée par IP, ville ou coordonnées.
      tags:
        - Météo
      parameters:
        - name: partner_id
          in: query
          required: true
          schema:
            type: string
            example: "sfr"
          description: Identifiant unique du partenaire
        - name: city
          in: query
          required: false
          schema:
            type: string
            example: "Lyon"
          description: Ville pour la météo (priorité sur la géolocalisation IP)
        - name: lat
          in: query
          required: false
          schema:
            type: number
            format: float
            example: 45.764043
          description: Latitude
        - name: lon
          in: query
          required: false
          schema:
            type: number
            format: float
            example: 4.835659
          description: Longitude
        - name: ip
          in: query
          required: false
          schema:
            type: string
            format: ipv4
            example: "192.168.1.1"
          description: IP pour géolocalisation manuelle
      responses:
        '200':
          description: Données météo récupérées avec succès
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WeatherResponse'
              example:
                location:
                  city: "Paris"
                  country: "France"
                  detected_by: "ip"
                  user_provided: false
                weather:
                  main: "clouds"
                  description: "nuageux"
                  temperature: 15
                  feels_like: 14
                  humidity: 75
                  wind_speed: 12.5
                  pressure: 1015
                images:
                  widget_portrait: "https://cdn.com/weather/portrait/cloudy.jpg"
                  landing_landscape: "https://cdn.com/weather/landscape/cloudy.jpg"
                  icon: "https://openweathermap.org/img/wn/04d.png"
                links:
                  landing_page: "https://meteo-site.com/sfr?utm_source=sfr&utm_medium=widget&utm_campaign=weather"
                timestamp: "2024-01-15T14:30:00Z"
        '400':
          description: Partner ID invalide ou inactif
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Paramètres de requête invalides
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'

components:
  schemas:
    WeatherResponse:
      type: object
      properties:
        location:
          $ref: '#/components/schemas/Location'
        weather:
          $ref: '#/components/schemas/WeatherData'
        images:
          $ref: '#/components/schemas/WeatherImages'
        links:
          $ref: '#/components/schemas/TrackingLinks'
        timestamp:
          type: string
          format: date-time
          example: "2024-01-15T14:30:00Z"

    Location:
      type: object
      properties:
        city:
          type: string
          example: "Paris"
        country:
          type: string
          example: "France"
        detected_by:
          type: string
          enum: [ip, city, coordinates, fallback]
          example: "ip"
        user_provided:
          type: boolean
          example: false

    WeatherData:
      type: object
      properties:
        main:
          type: string
          enum: [clear, clouds, rain, drizzle, thunderstorm, snow, mist, smoke, haze, dust, fog, sand, ash, squall, tornado]
          example: "clouds"
        description:
          type: string
          example: "nuageux"
        temperature:
          type: number
          format: float
          example: 15
        feels_like:
          type: number
          format: float
          example: 14
        humidity:
          type: integer
          minimum: 0
          maximum: 100
          example: 75
        wind_speed:
          type: number
          format: float
          example: 12.5
        pressure:
          type: integer
          example: 1015

    WeatherImages:
      type: object
      properties:
        widget_portrait:
          type: string
          format: uri
          example: "https://cdn.com/weather/portrait/cloudy.jpg"
        landing_landscape:
          type: string
          format: uri
          example: "https://cdn.com/weather/landscape/cloudy.jpg"
        icon:
          type: string
          format: uri
          example: "https://openweathermap.org/img/wn/04d.png"

    TrackingLinks:
      type: object
      properties:
        landing_page:
          type: string
          format: uri
          example: "https://meteo-site.com/sfr?utm_source=sfr&utm_medium=widget&utm_campaign=weather"

    Error:
      type: object
      properties:
        error:
          type: string
          example: "Invalid or inactive partner ID"

    ValidationError:
      type: object
      properties:
        message:
          type: string
          example: "The given data was invalid."
        errors:
          type: object
          properties:
            partner_id:
              type: array
              items:
                type: string
              example: ["The partner id field is required."]

  securitySchemes:
    PartnerAPIKey:
      type: apiKey
      in: query
      name: partner_id
      description: Clé API du partenaire

security:
  - PartnerAPIKey: []
