AIP-84 Improve doc for backfill API

airflow/api_fastapi/core_api/openapi/v1-generated.yaml

@@ -285,7 +285,8 @@ paths:
           description: Successful Response
           content:
             application/json:
-              schema: {}
+              schema:
+                $ref: '#/components/schemas/BackfillCollectionResponse'
         '401':
           content:
             application/json:
@@ -320,7 +321,8 @@ paths:
           description: Successful Response
           content:
             application/json:
-              schema: {}
+              schema:
+                $ref: '#/components/schemas/BackfillResponse'
         '401':
           content:
             application/json:
@@ -369,7 +371,8 @@ paths:
           description: Successful Response
           content:
             application/json:
-              schema: {}
+              schema:
+                $ref: '#/components/schemas/BackfillResponse'
         '401':
           content:
             application/json:
@@ -411,7 +414,8 @@ paths:
           description: Successful Response
           content:
             application/json:
-              schema: {}
+              schema:
+                $ref: '#/components/schemas/BackfillResponse'
         '401':
           content:
             application/json:
@@ -459,7 +463,8 @@ paths:
           description: Successful Response
           content:
             application/json:
-              schema: {}
+              schema:
+                $ref: '#/components/schemas/BackfillResponse'
         '401':
           content:
             application/json:
@@ -507,7 +512,8 @@ paths:
           description: Successful Response
           content:
             application/json:
-              schema: {}
+              schema:
+                $ref: '#/components/schemas/BackfillResponse'
         '401':
           content:
             application/json:
@@ -3503,6 +3509,22 @@ components:
       - aliases
       title: AssetResponse
       description: Asset serializer for responses.
+    BackfillCollectionResponse:
+      properties:
+        backfills:
+          items:
+            $ref: '#/components/schemas/BackfillResponse'
+          type: array
+          title: Backfills
+        total_entries:
+          type: integer
+          title: Total Entries
+      type: object
+      required:
+      - backfills
+      - total_entries
+      title: BackfillCollectionResponse
+      description: Backfill Collection serializer for responses.
     BackfillPostBody:
       properties:
         dag_id:
@@ -3538,6 +3560,62 @@ components:
       - to_date
       title: BackfillPostBody
       description: Object used for create backfill request.
+    BackfillResponse:
+      properties:
+        id:
+          type: integer
+          title: Id
+        dag_id:
+          type: string
+          title: Dag Id
+        from_date:
+          type: string
+          format: date-time
+          title: From Date
+        to_date:
+          type: string
+          format: date-time
+          title: To Date
+        dag_run_conf:
+          type: object
+          title: Dag Run Conf
+        is_paused:
+          type: boolean
+          title: Is Paused
+        reprocess_behavior:
+          $ref: '#/components/schemas/ReprocessBehavior'
+        max_active_runs:
+          type: integer
+          title: Max Active Runs
+        created_at:
+          type: string
+          format: date-time
+          title: Created At
+        completed_at:
+          anyOf:
+          - type: string
+            format: date-time
+          - type: 'null'
+          title: Completed At
+        updated_at:
+          type: string
+          format: date-time
+          title: Updated At
+      type: object
+      required:
+      - id
+      - dag_id
+      - from_date
+      - to_date
+      - dag_run_conf
+      - is_paused
+      - reprocess_behavior
+      - max_active_runs
+      - created_at
+      - completed_at
+      - updated_at
+      title: BackfillResponse
+      description: Base serializer for Backfill.
     BaseInfoSchema:
       properties:
         status:

airflow/api_fastapi/core_api/routes/public/backfills.py

@@ -59,7 +59,7 @@ def list_backfills(
         Depends(SortParam(["id"], Backfill).dynamic_depends()),
     ],
     session: Annotated[Session, Depends(get_session)],
-):
+) -> BackfillCollectionResponse:
     select_stmt, total_entries = paginated_select(
         select(Backfill).where(Backfill.dag_id == dag_id),
         [],
@@ -85,7 +85,7 @@ def list_backfills(
 def get_backfill(
     backfill_id: str,
     session: Annotated[Session, Depends(get_session)],
-):
+) -> BackfillResponse:
     backfill = session.get(Backfill, backfill_id)
     if backfill:
         return BackfillResponse.model_validate(backfill, from_attributes=True)
@@ -103,7 +103,7 @@ def get_backfill(
         ]
     ),
 )
-def pause_backfill(*, backfill_id, session: Annotated[Session, Depends(get_session)]):
+def pause_backfill(backfill_id, session: Annotated[Session, Depends(get_session)]) -> BackfillResponse:
     b = session.get(Backfill, backfill_id)
     if not b:
         raise HTTPException(status.HTTP_404_NOT_FOUND, f"Could not find backfill with id {backfill_id}")
@@ -126,7 +126,7 @@ def pause_backfill(*, backfill_id, session: Annotated[Session, Depends(get_sessi
         ]
     ),
 )
-def unpause_backfill(*, backfill_id, session: Annotated[Session, Depends(get_session)]):
+def unpause_backfill(backfill_id, session: Annotated[Session, Depends(get_session)]) -> BackfillResponse:
     b = session.get(Backfill, backfill_id)
     if not b:
         raise HTTPException(status.HTTP_404_NOT_FOUND, f"Could not find backfill with id {backfill_id}")
@@ -148,7 +148,7 @@ def unpause_backfill(*, backfill_id, session: Annotated[Session, Depends(get_ses
         ]
     ),
 )
-def cancel_backfill(*, backfill_id, session: Annotated[Session, Depends(get_session)]):
+def cancel_backfill(backfill_id, session: Annotated[Session, Depends(get_session)]) -> BackfillResponse:
     b: Backfill = session.get(Backfill, backfill_id)
     if not b:
         raise HTTPException(status.HTTP_404_NOT_FOUND, f"Could not find backfill with id {backfill_id}")
@@ -197,7 +197,7 @@ def cancel_backfill(*, backfill_id, session: Annotated[Session, Depends(get_sess
 )
 def create_backfill(
     backfill_request: BackfillPostBody,
-):
+) -> BackfillResponse:
     from_date = timezone.coerce_datetime(backfill_request.from_date)
     to_date = timezone.coerce_datetime(backfill_request.to_date)
     try:

airflow/ui/openapi-gen/queries/prefetch.ts

@@ -188,7 +188,7 @@ export const prefetchUseDagsServiceRecentDagRuns = (
  * @param data.limit
  * @param data.offset
  * @param data.orderBy
- * @returns unknown Successful Response
+ * @returns BackfillCollectionResponse Successful Response
  * @throws ApiError
  */
 export const prefetchUseBackfillServiceListBackfills = (
@@ -219,7 +219,7 @@ export const prefetchUseBackfillServiceListBackfills = (
  * Get Backfill
  * @param data The data for the request.
  * @param data.backfillId
- * @returns unknown Successful Response
+ * @returns BackfillResponse Successful Response
  * @throws ApiError
  */
 export const prefetchUseBackfillServiceGetBackfill = (

airflow/ui/openapi-gen/queries/queries.ts

@@ -234,7 +234,7 @@ export const useDagsServiceRecentDagRuns = <
  * @param data.limit
  * @param data.offset
  * @param data.orderBy
- * @returns unknown Successful Response
+ * @returns BackfillCollectionResponse Successful Response
  * @throws ApiError
  */
 export const useBackfillServiceListBackfills = <
@@ -269,7 +269,7 @@ export const useBackfillServiceListBackfills = <
  * Get Backfill
  * @param data The data for the request.
  * @param data.backfillId
- * @returns unknown Successful Response
+ * @returns BackfillResponse Successful Response
  * @throws ApiError
  */
 export const useBackfillServiceGetBackfill = <
@@ -1603,7 +1603,7 @@ export const useXcomServiceGetXcomEntry = <
  * Create Backfill
  * @param data The data for the request.
  * @param data.requestBody
- * @returns unknown Successful Response
+ * @returns BackfillResponse Successful Response
  * @throws ApiError
  */
 export const useBackfillServiceCreateBackfill = <
@@ -1799,7 +1799,7 @@ export const useVariableServicePostVariable = <
  * Pause Backfill
  * @param data The data for the request.
  * @param data.backfillId
- * @returns unknown Successful Response
+ * @returns BackfillResponse Successful Response
  * @throws ApiError
  */
 export const useBackfillServicePauseBackfill = <
@@ -1837,7 +1837,7 @@ export const useBackfillServicePauseBackfill = <
  * Unpause Backfill
  * @param data The data for the request.
  * @param data.backfillId
- * @returns unknown Successful Response
+ * @returns BackfillResponse Successful Response
  * @throws ApiError
  */
 export const useBackfillServiceUnpauseBackfill = <
@@ -1875,7 +1875,7 @@ export const useBackfillServiceUnpauseBackfill = <
  * Cancel Backfill
  * @param data The data for the request.
  * @param data.backfillId
- * @returns unknown Successful Response
+ * @returns BackfillResponse Successful Response
  * @throws ApiError
  */
 export const useBackfillServiceCancelBackfill = <

airflow/ui/openapi-gen/queries/suspense.ts

@@ -219,7 +219,7 @@ export const useDagsServiceRecentDagRunsSuspense = <
  * @param data.limit
  * @param data.offset
  * @param data.orderBy
- * @returns unknown Successful Response
+ * @returns BackfillCollectionResponse Successful Response
  * @throws ApiError
  */
 export const useBackfillServiceListBackfillsSuspense = <
@@ -254,7 +254,7 @@ export const useBackfillServiceListBackfillsSuspense = <
  * Get Backfill
  * @param data The data for the request.
  * @param data.backfillId
- * @returns unknown Successful Response
+ * @returns BackfillResponse Successful Response
  * @throws ApiError
  */
 export const useBackfillServiceGetBackfillSuspense = <

airflow/ui/openapi-gen/requests/schemas.gen.ts

@@ -194,6 +194,26 @@ export const $AssetResponse = {
   description: "Asset serializer for responses.",
 } as const;
 
+export const $BackfillCollectionResponse = {
+  properties: {
+    backfills: {
+      items: {
+        $ref: "#/components/schemas/BackfillResponse",
+      },
+      type: "array",
+      title: "Backfills",
+    },
+    total_entries: {
+      type: "integer",
+      title: "Total Entries",
+    },
+  },
+  type: "object",
+  required: ["backfills", "total_entries"],
+  title: "BackfillCollectionResponse",
+  description: "Backfill Collection serializer for responses.",
+} as const;
+
 export const $BackfillPostBody = {
   properties: {
     dag_id: {
@@ -236,6 +256,82 @@ export const $BackfillPostBody = {
   description: "Object used for create backfill request.",
 } as const;
 
+export const $BackfillResponse = {
+  properties: {
+    id: {
+      type: "integer",
+      title: "Id",
+    },
+    dag_id: {
+      type: "string",
+      title: "Dag Id",
+    },
+    from_date: {
+      type: "string",
+      format: "date-time",
+      title: "From Date",
+    },
+    to_date: {
+      type: "string",
+      format: "date-time",
+      title: "To Date",
+    },
+    dag_run_conf: {
+      type: "object",
+      title: "Dag Run Conf",
+    },
+    is_paused: {
+      type: "boolean",
+      title: "Is Paused",
+    },
+    reprocess_behavior: {
+      $ref: "#/components/schemas/ReprocessBehavior",
+    },
+    max_active_runs: {
+      type: "integer",
+      title: "Max Active Runs",
+    },
+    created_at: {
+      type: "string",
+      format: "date-time",
+      title: "Created At",
+    },
+    completed_at: {
+      anyOf: [
+        {
+          type: "string",
+          format: "date-time",
+        },
+        {
+          type: "null",
+        },
+      ],
+      title: "Completed At",
+    },
+    updated_at: {
+      type: "string",
+      format: "date-time",
+      title: "Updated At",
+    },
+  },
+  type: "object",
+  required: [
+    "id",
+    "dag_id",
+    "from_date",
+    "to_date",
+    "dag_run_conf",
+    "is_paused",
+    "reprocess_behavior",
+    "max_active_runs",
+    "created_at",
+    "completed_at",
+    "updated_at",
+  ],
+  title: "BackfillResponse",
+  description: "Base serializer for Backfill.",
+} as const;
+
 export const $BaseInfoSchema = {
   properties: {
     status: {