docs: 📝 openapi contracts of the new created endpoints

Author: marcvergees

contracts/openapi.yaml

@@ -31,6 +31,8 @@ tags:
     description: Health checks, schema introspection, and system status
   - name: jobs
     description: Cross-cutting async job status polling
+  - name: external-apis
+    description: Integrations with external APIs (Weather, Zipcode)
 
 paths:
   # ── Layer 1: Input ──────────────────────────────────────────────
@@ -96,3 +98,11 @@ paths:
   # ── Layer 8: Async Jobs ────────────────────────────────────────
   /api/v1/jobs/{job_id}:
     $ref: "path/jobs.yaml#/job_by_id"
+
+  # ── Layer 9: External APIs ─────────────────────────────────────
+  /api/v1/weather/forecast:
+    $ref: "path/weather.yaml#/forecast"
+  /api/v1/zipcode/postal-code:
+    $ref: "path/zipcode.yaml#/postal_code"
+  /api/v1/zipcode/location:
+    $ref: "path/zipcode.yaml#/location"

contracts/path/weather.yaml

@@ -0,0 +1,47 @@
+forecast:
+  get:
+    summary: Fetch weather forecast
+    description: Fetch weather data for the given location and fields.
+    tags:
+      - external-apis
+    parameters:
+      - name: latitude
+        in: query
+        required: true
+        schema:
+          type: number
+          format: float
+      - name: longitude
+        in: query
+        required: true
+        schema:
+          type: number
+          format: float
+      - name: start_date
+        in: query
+        required: true
+        schema:
+          type: string
+          format: date
+      - name: end_date
+        in: query
+        required: true
+        schema:
+          type: string
+          format: date
+      - name: fields
+        in: query
+        required: false
+        schema:
+          type: string
+        description: Comma-separated list of hourly variables to request.
+    responses:
+      '200':
+        description: Weather data retrieved successfully
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
+      '500':
+        description: Internal server error

contracts/path/zipcode.yaml

@@ -0,0 +1,57 @@
+postal_code:
+  get:
+    summary: Resolve postal code
+    description: Fetch data for the given postal code and country.
+    tags:
+      - external-apis
+    parameters:
+      - name: country
+        in: query
+        required: true
+        schema:
+          type: string
+      - name: postal_code
+        in: query
+        required: true
+        schema:
+          type: string
+    responses:
+      '200':
+        description: Postal code data retrieved successfully
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
+      '500':
+        description: Internal server error
+
+location:
+  get:
+    summary: Resolve location
+    description: Fetch data for the given city and country.
+    tags:
+      - external-apis
+    parameters:
+      - name: country
+        in: query
+        required: true
+        schema:
+          type: string
+      - name: city
+        in: query
+        required: true
+        schema:
+          type: string
+    responses:
+      '200':
+        description: Location data retrieved successfully
+        content:
+          application/json:
+            schema:
+              type: array
+              items:
+                type: object
+                additionalProperties: true
+      '500':
+        description: Internal server error