feat(platform-api): add per-operation upstream override to the OpenAPI schema

Author: mehara-rothila

platform-api/src/resources/openapi.yaml

@@ -6328,7 +6328,7 @@ components:
           $ref: "#/components/schemas/Upstream"
         upstreamDefinitions:
           type: array
-          description: List of reusable named upstream definitions. API-level upstream `ref` values resolve against entries here by name.
+          description: List of reusable named upstream definitions. Both API-level and operation-level upstream `ref` values resolve against entries here by name.
           items:
             $ref: '#/components/schemas/ReusableUpstream'
         lifeCycleStatus:
@@ -6478,6 +6478,8 @@ components:
           description: List of policies to be applied on the operation
           items:
             $ref: "#/components/schemas/Policy"
+        upstream:
+          $ref: "#/components/schemas/OperationUpstream"
 
     ChannelRequest:
       title: Channel Request
@@ -8389,6 +8391,39 @@ components:
         auth:
           $ref: '#/components/schemas/UpstreamAuth'
 
+    OperationUpstream:
+      title: Operation Upstream
+      type: object
+      additionalProperties: false
+      minProperties: 1
+      description: Per-operation upstream override. Each sub-field must reference a named entry in upstreamDefinitions. Missing sub-fields fall back to the API-level upstream. At least one of main or sandbox must be set.
+      properties:
+        main:
+          type: object
+          additionalProperties: false
+          required:
+            - ref
+          properties:
+            ref:
+              $ref: '#/components/schemas/UpstreamReference'
+        sandbox:
+          type: object
+          additionalProperties: false
+          required:
+            - ref
+          properties:
+            ref:
+              $ref: '#/components/schemas/UpstreamReference'
+
+    UpstreamReference:
+      title: Upstream Reference
+      type: string
+      description: Name of a ReusableUpstream entry in the API's upstreamDefinitions pool. Used by both API-level and operation-level upstream refs.
+      minLength: 1
+      maxLength: 100
+      pattern: '^[a-zA-Z0-9\-_]+$'
+      example: my-upstream-1
+
     UpstreamAuth:
       type: object
       description: Authentication configuration for upstream endpoints
@@ -8415,15 +8450,10 @@ components:
       required:
         - name
         - upstreams
-      description: A reusable named upstream definition. Referenced by name from an API-level upstream.ref.
+      description: A reusable named upstream definition. Referenced by name from API-level and operation-level upstream refs.
       properties:
         name:
-          type: string
-          description: Unique identifier for this upstream definition
-          minLength: 1
-          maxLength: 100
-          pattern: '^[a-zA-Z0-9\-_]+$'
-          example: my-upstream-1
+          $ref: '#/components/schemas/UpstreamReference'
         basePath:
           type: string
           description: Base path prefix prepended to all requests routed to this upstream (e.g., /api/v2)