Auto generate API docs

fylein · Dec 6, 2024 · 86d36a1 · 86d36a1
1 parent d230712
commit 86d36a1
Show file tree

Hide file tree

Showing 2 changed files with 144 additions and 34 deletions.
diff --git a/reference/admin.yaml b/reference/admin.yaml
@@ -4868,28 +4868,83 @@ components:
         custom_fields:
           $ref: '#/components/schemas/custom_fields'
     advance_requests_stats_in:
+      type: object
+      required:
+        - data
       properties:
         query_params:
-          type: string
           description: |
-            This field contains the query param string similar to the query params passed in advance_requests GET call for displaying advance_requests in the list view.
+            Query param string similar to advance_requests GET call. Use group_by_state=eq.true to get state-wise grouping of stats.
           nullable: false
-          example: id=in.('adr1263', 'adr1569')
+          example: id=in.('adr1263','adr1569')&group_by_state=eq.true
     advance_requests_stats_out:
-      type: object
-      properties:
-        count:
-          type: integer
-          description: |
-            This field represents the total number of advance_requests that match the criteria specified in the query_params within the body of the request.
-          nullable: false
-          example: 1
-        total_amount:
-          allOf:
-            - $ref: '#/components/schemas/amount'
-          description: |
-            This field indicates the sum of amount of advance_requests that match the criteria specified in the query_params within the body of the request.
-          example: 100
+      type: array
+      description: |
+        Array containing stats objects. When group_by_state is true, contains objects for ALL possible states 
+        (with count and total_amount as 0 for states with no matching advance requests). When false or not provided, 
+        contains single object with aggregated stats and null state.
+      items:
+        type: object
+        required:
+          - count
+          - total_amount
+          - state
+        properties:
+          count:
+            type: integer
+            nullable: false
+            description: |
+              Number of advance requests that match the specified criteria.
+            example: 10
+          total_amount:
+            type: number
+            nullable: false
+            description: |
+              Sum of amounts for matching advance requests.
+            example: 44545.4
+          state:
+            type: string
+            nullable: true
+            description: |
+              Advance request state for grouping. null when group_by_state is false or not provided.
+              When group_by_state is true, response includes all possible states, with count=0 
+              and total_amount=0 for states with no matching advance requests.
+            example: DRAFT
+            enum:
+              - DRAFT
+              - APPROVAL_PENDING
+              - APPROVED
+              - CANCELLED
+              - REJECTED
+              - PAID
+              - PULLED_BACK
+              - SENT_BACK
+              - null
+      example:
+        - state: DRAFT
+          count: 10
+          total_amount: 44545.4
+        - state: APPROVAL_PENDING
+          count: 0
+          total_amount: 0
+        - state: APPROVED
+          count: 343
+          total_amount: 1337
+        - state: CANCELLED
+          count: 0
+          total_amount: 0
+        - state: SENT_BACK
+          count: 0
+          total_amount: 0
+        - state: PULLED_BACK
+          count: 0
+          total_amount: 0
+        - state: REJECTED
+          count: 0
+          total_amount: 0
+        - state: PAID
+          count: 0
+          total_amount: 0
     advance_request_out_embed:
       type: object
       nullable: true

diff --git a/reference/spender.yaml b/reference/spender.yaml
@@ -3886,28 +3886,83 @@ components:
         custom_fields:
           $ref: '#/components/schemas/custom_fields'
     advance_requests_stats_in:
+      type: object
+      required:
+        - data
       properties:
         query_params:
-          type: string
           description: |
-            This field contains the query param string similar to the query params passed in advance_requests GET call for displaying advance_requests in the list view.
+            Query param string similar to advance_requests GET call. Use group_by_state=eq.true to get state-wise grouping of stats.
           nullable: false
-          example: id=in.('adr1263', 'adr1569')
+          example: id=in.('adr1263','adr1569')&group_by_state=eq.true
     advance_requests_stats_out:
-      type: object
-      properties:
-        count:
-          type: integer
-          description: |
-            This field represents the total number of advance_requests that match the criteria specified in the query_params within the body of the request.
-          nullable: false
-          example: 1
-        total_amount:
-          allOf:
-            - $ref: '#/components/schemas/amount'
-          description: |
-            This field indicates the sum of amount of advance_requests that match the criteria specified in the query_params within the body of the request.
-          example: 100
+      type: array
+      description: |
+        Array containing stats objects. When group_by_state is true, contains objects for ALL possible states 
+        (with count and total_amount as 0 for states with no matching advance requests). When false or not provided, 
+        contains single object with aggregated stats and null state.
+      items:
+        type: object
+        required:
+          - count
+          - total_amount
+          - state
+        properties:
+          count:
+            type: integer
+            nullable: false
+            description: |
+              Number of advance requests that match the specified criteria.
+            example: 10
+          total_amount:
+            type: number
+            nullable: false
+            description: |
+              Sum of amounts for matching advance requests.
+            example: 44545.4
+          state:
+            type: string
+            nullable: true
+            description: |
+              Advance request state for grouping. null when group_by_state is false or not provided.
+              When group_by_state is true, response includes all possible states, with count=0 
+              and total_amount=0 for states with no matching advance requests.
+            example: DRAFT
+            enum:
+              - DRAFT
+              - APPROVAL_PENDING
+              - APPROVED
+              - CANCELLED
+              - REJECTED
+              - PAID
+              - PULLED_BACK
+              - SENT_BACK
+              - null
+      example:
+        - state: DRAFT
+          count: 10
+          total_amount: 44545.4
+        - state: APPROVAL_PENDING
+          count: 0
+          total_amount: 0
+        - state: APPROVED
+          count: 343
+          total_amount: 1337
+        - state: CANCELLED
+          count: 0
+          total_amount: 0
+        - state: SENT_BACK
+          count: 0
+          total_amount: 0
+        - state: PULLED_BACK
+          count: 0
+          total_amount: 0
+        - state: REJECTED
+          count: 0
+          total_amount: 0
+        - state: PAID
+          count: 0
+          total_amount: 0
     advance_request_out_embed:
       type: object
       nullable: true