updated openAPI contract with examples

pradipmudi · Feb 4, 2024 · 025af4d · 025af4d
1 parent e8e4f4c
commit 025af4d
Showing 1 changed file with 215 additions and 82 deletions.
diff --git a/src/main/java/com/expensys/openapi/expensys_openapi.yml b/src/main/java/com/expensys/openapi/expensys_openapi.yml
@@ -1,13 +1,13 @@
 openapi: 3.0.3
 info:
-  title: Expense Management System
+  title: ExpenseTrackr a.k.a. ExpenSys a.k.a. Expense Management System
   version: 1.0.0
 servers:
   - url: http://localhost:8080
 paths:
   /report:
     get:
-      summary: Retrieve Report Data for Expenses by Month, YEAR, User, Main Category, and Subcategory
+      summary: Retrieve Report Data for Expenses by Month, Year, User, Main Category, and Subcategory
       parameters:
         - name: month
           in: query
@@ -59,93 +59,75 @@ paths:
         - name: year
           in: query
           description: The year for the report (e.g., 2023)
-          required: false
+          required: true
           schema:
             type: integer
       responses:
         '200':
           description: Successful Response
           content:
             application/json:
-              example:
-                - month: OCTOBER
-                  totalSpendings: 81678
-                  reportInfo:
-                    - mainCategory: ESSENTIAL
-                      subCategory: essential
-                      spent: 22340
-                      user: John
-                    - mainCategory: EXPENSE
-                      subCategory: expense
-                      spent: 1608
-                      user: John
-                    - mainCategory: ESSENTIAL
-                      subCategory: essential
-                      spent: 4380
-                      user: Alice
-                    - mainCategory: EXPENSE
-                      subCategory: expense
-                      spent: 4781
-                      user: Alice
-                    - mainCategory: ESSENTIAL
-                      subCategory: essential
-                      spent: 37316
-                      user: ALL
-                    - mainCategory: EXPENSE
-                      subCategory: expense
-                      spent: 11211
-                      user: ALL
-                    - mainCategory: EXPENSE
-                      subCategory: expense
-                      spent: 42
-                      user: ALL
-                - month: AUGUST
-                  totalSpendings: 42295
-                  reportInfo:
-                    - mainCategory: ESSENTIAL
-                      subCategory: essential
-                      spent: 210
-                      user: Jane
-                    - mainCategory: ESSENTIAL
-                      subCategory: essential
-                      spent: 22391
-                      user: John
-                    - mainCategory: LOSE_OF_MONEY
-                      subCategory: lose of money
-                      spent: 6050
-                      user: John
-                    - mainCategory: EXPENSE
-                      subCategory: expense
-                      spent: 6643
-                      user: John
-                    - mainCategory: ESSENTIAL
-                      subCategory: essential
-                      spent: 200
-                      user: John
-                    - mainCategory: ESSENTIAL
-                      subCategory: essential
-                      spent: 1800
-                      user: Alice
-                    - mainCategory: EXPENSE
-                      subCategory: expense
-                      spent: 820
-                      user: Alice
-                    - mainCategory: ESSENTIAL
-                      subCategory: essential
-                      spent: 180
-                      user: Alice
-                    - mainCategory: EXPENSE
-                      subCategory: expense
-                      spent: 1120
-                      user: Alice
-                    - mainCategory: ESSENTIAL
-                      subCategory: essential
-                      spent: 2021
-                      user: ALL
-                    - mainCategory: EXPENSE
-                      subCategory: expense
-                      spent: 860
-                      user: ALL
+              schema:
+                $ref: '#/components/schemas/MonthlyReport'
+              examples:
+                example1:
+                  value:
+                    - month: OCTOBER
+                      totalSpendings: 81678
+                      reportInfo:
+                        - mainCategory: ESSENTIAL
+                          subCategory: ESSENTIAL
+                          spent: 22340
+                          user: John
+                        - mainCategory: EXPENSE
+                          subCategory: EXPENSE
+                          spent: 1608
+                          user: John
+                        - mainCategory: ESSENTIAL
+                          subCategory: ESSENTIAL
+                          spent: 4380
+                          user: Alice
+                        - mainCategory: EXPENSE
+                          subCategory: EXPENSE
+                          spent: 4781
+                          user: Alice
+                        - mainCategory: ESSENTIAL
+                          subCategory: ESSENTIAL
+                          spent: 37316
+                          user: ALL
+                        - mainCategory: EXPENSE
+                          subCategory: EXPENSE
+                          spent: 11211
+                          user: ALL
+                        - mainCategory: EXPENSE
+                          subCategory: EXPENSE
+                          spent: 42
+                          user: ALL
+                example2:
+                  value:
+                    - month: FEBRUARY
+                      totalSpendings: 18236.7
+                      reportInfo:
+                        - subCategory: RENT_AND_OTHER_BILLS
+                          mainCategory: EXPENSE
+                          spent: 15533.0
+                          spentBy: ALL
+                        - subCategory: GROCERIES
+                          mainCategory: ESSENTIAL
+                          spent: 1050.0
+                          spentBy: ALL
+                        - subCategory: VEGETABLES_FRUITS_DAIRY_AND_MEAT
+                          mainCategory: ESSENTIAL
+                          spent: 992.68
+                          spentBy: ALL
+                        - subCategory: TRANSPORT
+                          mainCategory: EXPENSE
+                          spent: 561.02
+                          spentBy: John
+                        - subCategory: OUTSIDE_FOOD
+                          mainCategory: EXPENSE
+                          spent: 100.0
+                          spentBy: ALL
         '400':
           description: Bad Request
           content:
@@ -158,3 +140,154 @@ paths:
             application/json:
               example:
                 - message: "An internal server error occurred. Please try again later."
+
+  /expense/{year}/{month}:
+    get:
+      summary: Get expenses for a specific year and month
+      parameters:
+        - name: year
+          in: path
+          required: true
+          description: The year for which expenses are requested (e.g., 2024)
+          schema:
+            type: integer
+            format: int32
+        - name: month
+          in: path
+          required: true
+          description: The month for which expenses are requested (e.g., FEBRUARY)
+          schema:
+            type: string
+            enum:
+              - ALL
+              - JANUARY
+              - FEBRUARY
+              - MARCH
+              - APRIL
+              - MAY
+              - JUNE
+              - JULY
+              - AUGUST
+              - SEPTEMBER
+              - OCTOBER
+              - NOVEMBER
+              - DECEMBER
+
+      responses:
+        '200':
+          description: Successful response with the list of expenses
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Expense'
+              example:
+                - id: 1
+                  date: "2024-02-01"
+                  item: "dummy item 1"
+                  category: "RENT_AND_OTHER_BILLS"
+                  spent: 50.0
+                  spentBy: "user1"
+                - id: 2
+                  date: "2024-02-01"
+                  item: "dummy item 2"
+                  category: "VEGETABLES_FRUITS_DAIRY_AND_MEAT"
+                  spent: 30.0
+                  spentBy: "user2"
+                - id: 3
+                  date: "2024-02-02"
+                  item: "dummy item 3"
+                  category: "TRANSPORT"
+                  spent: 25.0
+                  spentBy: "user1"
+        '404':
+          description: Expenses not found for the specified year and month
+        '500':
+          description: Internal Server Error
+          content:
+            application/json:
+              example:
+                - message: "An internal server error occurred. Please try again later."
+
+components:
+  schemas:
+    MonthlyReport:
+      type: object
+      properties:
+        month:
+          type: string
+          enum:
+            - ALL
+            - JANUARY
+            - FEBRUARY
+            - MARCH
+            - APRIL
+            - MAY
+            - JUNE
+            - JULY
+            - AUGUST
+            - SEPTEMBER
+            - OCTOBER
+            - NOVEMBER
+            - DECEMBER
+        totalSpendings:
+          type: number
+        reportInfo:
+          type: array
+          items:
+            $ref: '#/components/schemas/ReportInfo'
+
+    ReportInfo:
+      type: object
+      properties:
+        mainCategory:
+          type: string
+          enum:
+            - ESSENTIAL
+            - EXPENSE
+            - LOSE_OF_MONEY
+        subCategory:
+          type: string
+          enum:
+            - GROCERIES
+            - VEGETABLES_FRUITS_DAIRY_AND_MEAT
+            - MEDICAL
+            - SALON_AND_COSMETICS
+            - TRANSPORT
+            - SHOPPING
+            - OUTSIDE_FOOD
+            - LOSE_OF_MONEY
+            - ESSENTIAL
+            - EXPENSE
+            - ENTERTAINMENT
+            - RENT_AND_OTHER_BILLS
+            - INVESTMENTS
+            - OTHERS
+        spent:
+          type: number
+        user:
+          type: string
+          example:
+            - John
+    Expense:
+      type: object
+      properties:
+        id:
+          type: integer
+          example: 1
+        date:
+          type: string
+          example: "2024-02-01"
+        item:
+          type: string
+          example: "dummy item 1"
+        category:
+          type: string
+          example: "TRANSPORT"
+        spent:
+          type: number
+          example: 50.0
+        spentBy:
+          type: string
+          example: "user1"