[Issue 645] Restructure error response format

api/openapi.generated.yml

@@ -28,24 +28,25 @@ paths:
                   status_code:
                     type: integer
                     description: The HTTP status code
-                  warnings:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/ValidationError'
-                  errors:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/ValidationError'
                   pagination_info:
                     description: The pagination information for paginated endpoints
+                    type:
+                    - object
                     allOf:
                     - $ref: '#/components/schemas/PaginationInfo'
+                  warnings:
+                    type: array
+                    items:
+                      type:
+                      - object
+                      allOf:
+                      - $ref: '#/components/schemas/ValidationIssue'
           description: Successful response
         '503':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/HTTPError'
+                $ref: '#/components/schemas/ErrorResponse'
           description: Service Unavailable
       tags:
       - Health
@@ -76,30 +77,31 @@ paths:
                   status_code:
                     type: integer
                     description: The HTTP status code
-                  warnings:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/ValidationError'
-                  errors:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/ValidationError'
                   pagination_info:
                     description: The pagination information for paginated endpoints
+                    type:
+                    - object
                     allOf:
                     - $ref: '#/components/schemas/PaginationInfo'
+                  warnings:
+                    type: array
+                    items:
+                      type:
+                      - object
+                      allOf:
+                      - $ref: '#/components/schemas/ValidationIssue'
           description: Successful response
         '422':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ValidationError'
+                $ref: '#/components/schemas/ErrorResponse'
           description: Validation error
         '401':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/HTTPError'
+                $ref: '#/components/schemas/ErrorResponse'
           description: Authentication error
       tags:
       - Opportunity
@@ -134,30 +136,31 @@ paths:
                   status_code:
                     type: integer
                     description: The HTTP status code
-                  warnings:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/ValidationError'
-                  errors:
-                    type: array
-                    items:
-                      $ref: '#/components/schemas/ValidationError'
                   pagination_info:
                     description: The pagination information for paginated endpoints
+                    type:
+                    - object
                     allOf:
                     - $ref: '#/components/schemas/PaginationInfo'
+                  warnings:
+                    type: array
+                    items:
+                      type:
+                      - object
+                      allOf:
+                      - $ref: '#/components/schemas/ValidationIssue'
           description: Successful response
         '401':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/HTTPError'
+                $ref: '#/components/schemas/ErrorResponse'
           description: Authentication error
         '404':
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/HTTPError'
+                $ref: '#/components/schemas/ErrorResponse'
           description: Not found
       tags:
       - Opportunity
@@ -167,24 +170,6 @@ paths:
 openapi: 3.1.0
 components:
   schemas:
-    ValidationError:
-      type: object
-      properties:
-        type:
-          type: string
-          description: The type of error
-        message:
-          type: string
-          description: The message to return
-        rule:
-          type: string
-          description: The rule that failed
-        field:
-          type: string
-          description: The field that failed
-        value:
-          type: string
-          description: The value that failed
     PaginationInfo:
       type: object
       properties:
@@ -213,16 +198,43 @@ components:
           enum:
           - ascending
           - descending
-    HTTPError:
+          type:
+          - string
+    ValidationIssue:
+      type: object
       properties:
-        detail:
-          type: object
+        type:
+          type: string
+          description: The type of error
         message:
           type: string
-      type: object
+          description: The message to return
+        field:
+          type: string
+          description: The field that failed
     Healthcheck:
       type: object
-      properties: {}
+      properties:
+        message:
+          type: string
+    ErrorResponse:
+      type: object
+      properties:
+        message:
+          type: string
+          description: The message to return
+        data:
+          description: The REST resource object
+        status_code:
+          type: integer
+          description: The HTTP status code
+        errors:
+          type: array
+          items:
+            type:
+            - object
+            allOf:
+            - $ref: '#/components/schemas/ValidationIssue'
     OpportunitySorting:
       type: object
       properties:
@@ -240,6 +252,8 @@ components:
           enum:
           - ascending
           - descending
+          type:
+          - string
       required:
       - order_by
       - sort_direction
@@ -276,10 +290,18 @@ components:
           - C
           - E
           - O
+          type:
+          - string
         sorting:
-          $ref: '#/components/schemas/OpportunitySorting'
+          type:
+          - object
+          allOf:
+          - $ref: '#/components/schemas/OpportunitySorting'
         paging:
-          $ref: '#/components/schemas/Pagination'
+          type:
+          - object
+          allOf:
+          - $ref: '#/components/schemas/Pagination'
       required:
       - paging
       - sorting
@@ -313,6 +335,8 @@ components:
           - C
           - E
           - O
+          type:
+          - string
         created_at:
           type: string
           format: date-time

api/src/api/healthcheck.py

@@ -8,13 +8,13 @@
 
 import src.adapters.db.flask_db as flask_db
 from src.api import response
-from src.api.schemas import request_schema
+from src.api.schemas.extension import Schema, fields
 
 logger = logging.getLogger(__name__)
 
 
-class HealthcheckSchema(request_schema.OrderedSchema):
-    message: str
+class HealthcheckSchema(Schema):
+    message = fields.String()
 
 
 healthcheck_blueprint = APIBlueprint("healthcheck", __name__, tag="Health")

api/src/api/opportunities/opportunity_schemas.py

@@ -1,16 +1,15 @@
 from typing import Any
 
-from apiflask import fields
 from marshmallow import post_load
 
 from src.api.feature_flags.feature_flag import FeatureFlag
 from src.api.feature_flags.feature_flag_config import FeatureFlagConfig, get_feature_flag_config
-from src.api.schemas import request_schema
+from src.api.schemas.extension import Schema, fields
 from src.constants.lookup_constants import OpportunityCategory
 from src.pagination.pagination_schema import PaginationSchema, generate_sorting_schema
 
 
-class OpportunitySchema(request_schema.OrderedSchema):
+class OpportunitySchema(Schema):
     opportunity_id = fields.Integer(
         dump_only=True,
         metadata={"description": "The internal ID of the opportunity", "example": 12345},
@@ -31,7 +30,6 @@ class OpportunitySchema(request_schema.OrderedSchema):
 
     category = fields.Enum(
         OpportunityCategory,
-        by_value=True,
         metadata={
             "description": "The opportunity category",
             "example": OpportunityCategory.DISCRETIONARY,
@@ -42,7 +40,7 @@ class OpportunitySchema(request_schema.OrderedSchema):
     updated_at = fields.DateTime(dump_only=True)
 
 
-class OpportunitySearchSchema(request_schema.OrderedSchema):
+class OpportunitySearchSchema(Schema):
     opportunity_title = fields.String(
         metadata={
             "description": "The title of the opportunity to search for",
@@ -51,7 +49,6 @@ class OpportunitySearchSchema(request_schema.OrderedSchema):
     )
     category = fields.Enum(
         OpportunityCategory,
-        by_value=True,
         metadata={
             "description": "The opportunity category to search for",
             "example": OpportunityCategory.DISCRETIONARY,
@@ -74,7 +71,7 @@ class OpportunitySearchSchema(request_schema.OrderedSchema):
     paging = fields.Nested(PaginationSchema(), required=True)
 
 
-class OpportunitySearchHeaderSchema(request_schema.OrderedSchema):
+class OpportunitySearchHeaderSchema(Schema):
     # Header field: FF-Enable-Opportunity-Log-Msg
     enable_opportunity_log_msg = fields.Boolean(
         data_key=FeatureFlag.ENABLE_OPPORTUNITY_LOG_MSG.get_header_name(),