chore: document portfolio funding summary endpoint (#3502)

* chore: document portfolio funding summary endpoint * fix: add response schema * fix: add draft funding to schema
HHS · Feb 27, 2025 · 38b0928 · 38b0928
1 parent a80244c
commit 38b0928
Show file tree

Hide file tree

Showing 4 changed files with 107 additions and 2 deletions.
diff --git a/backend/openapi.yml b/backend/openapi.yml
@@ -1129,6 +1129,65 @@ paths:
                         "purpose": ""
                       }
                     ]
+  /api/v1/portfolio-funding-summary/{portfolio_id}:
+    get:
+      tags:
+        - Portfolio Funding Summary
+      summary: Get the funding summary for a specific portfolio
+      operationId: getPortfolioFundingSummary
+      description: Retrieve the funding summary for a given portfolio by its ID.
+      parameters:
+        - $ref: "#/components/parameters/simulatedError"
+        - in: path
+          name: portfolio_id
+          description: Portfolio ID
+          required: true
+          schema:
+            type: integer
+            format: int32
+        - name: fiscal_year
+          in: query
+          description: Fiscal year for which the funding summary is requested
+          schema:
+            type: integer
+      responses:
+        "200":
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PortfolioFundingSummary"
+              example:
+                value:
+                  total_funding:
+                    amount: 1000000.00
+                    percent: "Total"
+                  carry_forward_funding:
+                    amount: 200000.00
+                    percent: "Carry-Forward"
+                  draft_funding:
+                    amount: 50000.00
+                    percent: "5"
+                  planned_funding:
+                    amount: 300000.00
+                    percent: "30"
+                  obligated_funding:
+                    amount: 400000.00
+                    percent: "40"
+                  in_execution_funding:
+                    amount: 100000.00
+                    percent: "10"
+                  available_funding:
+                    amount: 150000.00
+                    percent: "15"
+        "400":
+          description: Bad Request
+        "401":
+          description: Unauthorized
+        "404":
+          description: Portfolio not found
+        "500":
+          description: Internal Server Error
   /api/v1/can-funding-summary:
     get:
       tags:
@@ -3217,6 +3276,32 @@ components:
         - id
         - portfolio_id
         - url
+    PortfolioFundingSummary:
+      description: Portfolio funding summary
+      type: object
+      properties:
+        total_funding:
+          $ref: "#/components/schemas/FundingLineItem"
+        carry_forward_funding:
+          $ref: "#/components/schemas/FundingLineItem"
+        draft_funding:
+          $ref: "#/components/schemas/FundingLineItem"
+        planned_funding:
+          $ref: "#/components/schemas/FundingLineItem"
+        obligated_funding:
+          $ref: "#/components/schemas/FundingLineItem"
+        in_execution_funding:
+          $ref: "#/components/schemas/FundingLineItem"
+        available_funding:
+          $ref: "#/components/schemas/FundingLineItem"
+    FundingLineItem:
+      description: Portfolio funding object
+      type: object
+      properties:
+        amount:
+          type: number
+        percentage:
+          type: string
     User:
       description: OPRE User Object
       type: object

diff --git a/backend/ops_api/ops/resources/portfolio_funding_summary.py b/backend/ops_api/ops/resources/portfolio_funding_summary.py
@@ -4,7 +4,7 @@
 from ops_api.ops.auth.auth_types import Permission, PermissionType
 from ops_api.ops.auth.decorators import is_authorized
 from ops_api.ops.base_views import BaseItemAPI
-from ops_api.ops.schemas.portfolio_funding_summary import RequestSchema
+from ops_api.ops.schemas.portfolio_funding_summary import RequestSchema, ResponseSchema
 from ops_api.ops.utils.fiscal_year import get_current_fiscal_year
 from ops_api.ops.utils.portfolios import get_total_funding
 from ops_api.ops.utils.response import make_response_with_headers
@@ -23,5 +23,9 @@ def get(self, id: int) -> Response:
         data = schema.load(request.args)
 
         portfolio = self._get_item(id)
-        portfolio_funding_summary = get_total_funding(portfolio, data.get("fiscal_year", get_current_fiscal_year()))
+
+        response_schema = ResponseSchema()
+        portfolio_funding_summary = response_schema.dump(
+            get_total_funding(portfolio, data.get("fiscal_year", get_current_fiscal_year()))
+        )
         return make_response_with_headers(portfolio_funding_summary)
diff --git a/backend/ops_api/ops/schemas/portfolio_funding_summary.py b/backend/ops_api/ops/schemas/portfolio_funding_summary.py
@@ -3,3 +3,18 @@
 
 class RequestSchema(Schema):
     fiscal_year = fields.Integer(allow_none=True)
+
+
+class FundingLineItem(Schema):
+    amount = fields.Float(required=True)
+    percent = fields.String(required=True)
+
+
+class ResponseSchema(Schema):
+    total_funding = fields.Nested(FundingLineItem)
+    carry_forward_funding = fields.Nested(FundingLineItem)
+    planned_funding = fields.Nested(FundingLineItem)
+    obligated_funding = fields.Nested(FundingLineItem)
+    in_execution_funding = fields.Nested(FundingLineItem)
+    available_funding = fields.Nested(FundingLineItem)
+    draft_funding = fields.Nested(FundingLineItem)
diff --git a/backend/ops_api/ops/utils/portfolios.py b/backend/ops_api/ops/utils/portfolios.py
@@ -23,6 +23,7 @@ class TotalFunding(TypedDict):
     obligated_funding: FundingLineItem
     in_execution_funding: FundingLineItem
     available_funding: FundingLineItem
+    draft_funding: FundingLineItem
 
 
 def _get_all_budgets(portfolio_id: int, fiscal_year: int) -> list[CANFundingBudget]: