Add categories endpoint in API (#460)

* Add categories endpoint in API

* FIX eager load parent and subcategories associations

* FIX update specs to match

* Add rswag spec

* FIX openapi spec

* FIX final warns

docs/api/openapi.yaml

@@ -242,6 +242,67 @@ components:
           type: string
         icon:
           type: string
+    CategoryParent:
+      type: object
+      required:
+      - id
+      - name
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+    CategoryDetail:
+      type: object
+      required:
+      - id
+      - name
+      - classification
+      - color
+      - icon
+      - subcategories_count
+      - created_at
+      - updated_at
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        classification:
+          type: string
+          enum:
+          - income
+          - expense
+        color:
+          type: string
+        icon:
+          type: string
+        parent:
+          "$ref": "#/components/schemas/CategoryParent"
+          nullable: true
+        subcategories_count:
+          type: integer
+          minimum: 0
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    CategoryCollection:
+      type: object
+      required:
+      - categories
+      - pagination
+      properties:
+        categories:
+          type: array
+          items:
+            "$ref": "#/components/schemas/CategoryDetail"
+        pagination:
+          "$ref": "#/components/schemas/Pagination"
     Merchant:
       type: object
       required:
@@ -356,6 +417,94 @@ components:
         message:
           type: string
 paths:
+  "/api/v1/categories":
+    get:
+      summary: List categories
+      tags:
+      - Categories
+      security:
+      - bearerAuth: []
+      parameters:
+      - name: Authorization
+        in: header
+        required: true
+        schema:
+          type: string
+        description: Bearer token with read scope
+      - name: page
+        in: query
+        required: false
+        description: 'Page number (default: 1)'
+        schema:
+          type: integer
+      - name: per_page
+        in: query
+        required: false
+        description: 'Items per page (default: 25, max: 100)'
+        schema:
+          type: integer
+      - name: classification
+        in: query
+        required: false
+        description: Filter by classification (income or expense)
+        schema:
+          type: string
+          enum:
+          - income
+          - expense
+      - name: roots_only
+        in: query
+        required: false
+        description: Return only root categories (no parent)
+        schema:
+          type: boolean
+      - name: parent_id
+        in: query
+        required: false
+        description: Filter by parent category ID
+        schema:
+          type: string
+          format: uuid
+      responses:
+        '200':
+          description: categories filtered by parent
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/CategoryCollection"
+  "/api/v1/categories/{id}":
+    parameters:
+    - name: Authorization
+      in: header
+      required: true
+      schema:
+        type: string
+      description: Bearer token with read scope
+    - name: id
+      in: path
+      required: true
+      description: Category ID
+      schema:
+        type: string
+    get:
+      summary: Retrieve a category
+      tags:
+      - Categories
+      security:
+      - bearerAuth: []
+      responses:
+        '200':
+          description: subcategory retrieved with parent
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/CategoryDetail"
+        '404':
+          description: category not found
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
   "/api/v1/chats":
     get:
       summary: List chats
@@ -420,13 +569,12 @@ paths:
                   example: Monthly budget review
                 message:
                   type: string
-                  description: Initial message in the chat
+                  description: Optional initial message in the chat
                 model:
                   type: string
                   description: Optional OpenAI model identifier
               required:
               - title
-              - message
         required: true
   "/api/v1/chats/{id}":
     parameters:
@@ -646,18 +794,18 @@ paths:
           type: string
       - name: start_date
         in: query
-        format: date
         required: false
         description: Filter transactions from this date
         schema:
           type: string
+          format: date
       - name: end_date
         in: query
-        format: date
         required: false
         description: Filter transactions until this date
         schema:
           type: string
+          format: date
       - name: min_amount
         in: query
         required: false
@@ -672,19 +820,51 @@ paths:
           type: number
       - name: type
         in: query
-        enum:
-        - income
-        - expense
         required: false
-        description: "Filter by transaction type:\n * `income` \n * `expense` \n "
+        description: Filter by transaction type
         schema:
           type: string
+          enum:
+          - income
+          - expense
       - name: search
         in: query
         required: false
         description: Search by name, notes, or merchant name
         schema:
           type: string
+      - name: account_ids
+        in: query
+        required: false
+        description: Filter by multiple account IDs
+        schema:
+          type: array
+          items:
+            type: string
+      - name: category_ids
+        in: query
+        required: false
+        description: Filter by multiple category IDs
+        schema:
+          type: array
+          items:
+            type: string
+      - name: merchant_ids
+        in: query
+        required: false
+        description: Filter by multiple merchant IDs
+        schema:
+          type: array
+          items:
+            type: string
+      - name: tag_ids
+        in: query
+        required: false
+        description: Filter by tag IDs
+        schema:
+          type: array
+          items:
+            type: string
       responses:
         '200':
           description: transactions filtered by date range
@@ -741,6 +921,9 @@ paths:
                     name:
                       type: string
                       description: Transaction name/description
+                    description:
+                      type: string
+                      description: Alternative to name field
                     notes:
                       type: string
                       description: Additional notes
@@ -846,8 +1029,14 @@ paths:
                       type: number
                     name:
                       type: string
+                    description:
+                      type: string
+                      description: Alternative to name field
                     notes:
                       type: string
+                    currency:
+                      type: string
+                      description: Currency code
                     category_id:
                       type: string
                       format: uuid