openapi: 3.0.0
info:
  title: FlyingWX Aviation Weather API
  description: |
    Professional REST API for aviation weather data including METAR, TAF, and intelligent minima checking.
    Built for flight planning systems, pilot tools, and aviation applications.
  version: 1.0.0
  contact:
    name: FlyingWX Support
    email: karthik.venkatesan@flyingwx.com
    url: https://api.flyingwx.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.flyingwx.com
    description: Production API
  - url: http://localhost:3000
    description: Development API

security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API Key for authentication

  schemas:
    WeatherData:
      type: object
      properties:
        metar:
          type: string
          description: Raw METAR data
          example: "KJFK 181851Z 32005KT 10SM FEW250 06/M06 A3034"
        taf:
          type: string
          description: Raw TAF data
          example: "KJFK 180720Z 1809/1912 31008KT P6SM SKC"
        timestamp:
          type: string
          format: date-time
          description: Timestamp of weather observation
    
    Minima:
      type: object
      properties:
        ceiling:
          type: number
          description: Ceiling in feet
          example: 1000
        vis:
          type: number
          description: Visibility in statute miles
          example: 3
    
    Timeline:
      type: object
      properties:
        fromDate:
          type: string
          format: date
          description: Start date (YYYY-MM-DD)
          example: "2026-01-18"
        fromTime:
          type: string
          description: Start time (HH:MM)
          example: "12:00"
        toDate:
          type: string
          format: date
          description: End date (YYYY-MM-DD)
          example: "2026-01-18"
        toTime:
          type: string
          description: End time (HH:MM)
          example: "18:00"
    
    MinimaMeetsResponse:
      type: object
      properties:
        meetsMinima:
          type: boolean
          description: Whether conditions meet the specified minima
        status:
          type: string
          enum: [ABOVE, BELOW]
          description: Status relative to minima
        affectingConditions:
          type: array
          items:
            type: string
          description: Weather conditions affecting the determination
    
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error type
        message:
          type: string
          description: Detailed error message
        details:
          type: string
          description: Additional error details

paths:
  /api/weather:
    get:
      summary: Fetch METAR and TAF data
      description: Retrieve both METAR and TAF weather data for specified stations
      tags:
        - Weather
      parameters:
        - name: stations
          in: query
          required: true
          schema:
            type: string
            example: "KJFK,KLAX,EGLL"
          description: Comma-separated list of ICAO station codes (max 50)
      responses:
        '200':
          description: Successfully retrieved weather data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  timestamp:
                    type: string
                    format: date-time
                  stationsRequested:
                    type: array
                    items:
                      type: string
                  data:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/WeatherData'
        '400':
          description: Bad request (missing or invalid stations parameter)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/weather/metar:
    get:
      summary: Fetch METAR data only
      description: Retrieve METAR observations for specified stations
      tags:
        - Weather
      parameters:
        - name: stations
          in: query
          required: true
          schema:
            type: string
            example: "KJFK,EGLL"
          description: Comma-separated list of ICAO station codes
      responses:
        '200':
          description: Successfully retrieved METAR data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  timestamp:
                    type: string
                    format: date-time
                  dataType:
                    type: string
                    enum: [METAR]
                  data:
                    type: object
                    additionalProperties:
                      type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/weather/taf:
    get:
      summary: Fetch TAF data only
      description: Retrieve TAF forecasts for specified stations
      tags:
        - Weather
      parameters:
        - name: stations
          in: query
          required: true
          schema:
            type: string
            example: "KJFK,EGLL"
          description: Comma-separated list of ICAO station codes
      responses:
        '200':
          description: Successfully retrieved TAF data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  timestamp:
                    type: string
                    format: date-time
                  dataType:
                    type: string
                    enum: [TAF]
                  data:
                    type: object
                    additionalProperties:
                      type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/minima/check:
    post:
      summary: Check if weather meets minima during timeline
      description: Analyze weather conditions against specified minima for a timeline period
      tags:
        - Minima
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - stations
                - minima
                - timeline
              properties:
                stations:
                  type: array
                  items:
                    type: string
                  example: ["KJFK", "KLAX"]
                  description: Array of ICAO station codes
                minima:
                  $ref: '#/components/schemas/Minima'
                timeline:
                  $ref: '#/components/schemas/Timeline'
      responses:
        '200':
          description: Minima check completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  timestamp:
                    type: string
                    format: date-time
                  minima:
                    $ref: '#/components/schemas/Minima'
                  timeline:
                    type: string
                    description: Formatted timeline string
                  results:
                    type: object
                    additionalProperties:
                      $ref: '#/components/schemas/MinimaMeetsResponse'
        '400':
          description: Bad request (missing or invalid parameters)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/audit:
    post:
      summary: Generate detailed TAF audit report
      description: Create a comprehensive TAF analysis with condition-by-condition breakdown and minima checking
      tags:
        - Audit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - station
                - minima
              properties:
                station:
                  type: string
                  example: "KJFK"
                  description: ICAO station code
                minima:
                  $ref: '#/components/schemas/Minima'
                timeline:
                  $ref: '#/components/schemas/Timeline'
                  description: Optional timeline for analysis
      responses:
        '200':
          description: TAF audit report generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  timestamp:
                    type: string
                    format: date-time
                  station:
                    type: string
                  tafText:
                    type: string
                    description: Raw TAF data
                  audit:
                    type: object
                    description: Detailed audit analysis
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Station not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

tags:
  - name: Weather
    description: METAR and TAF weather data endpoints
  - name: Minima
    description: Minima checking and analysis endpoints
  - name: Audit
    description: TAF audit and analysis endpoints