Add per-status error examples so each error response shows correct code and message

Author: beran-t

openapi-public.yml

@@ -1800,24 +1800,36 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+              example: &id009
+                code: 401
+                message: 'Authentication error: missing or invalid API key'
         '400':
           description: Invalid path
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+              example: &id008
+                code: 400
+                message: 'Bad request: invalid or missing request parameters'
         '404':
           description: File not found
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+              example: &id011
+                code: 404
+                message: 'Not found: the requested resource does not exist'
         '500':
           description: Internal server error
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+              example: &id010
+                code: 500
+                message: 'Server error: an unexpected error occurred'
         '502': *id003
       operationId: downloadFile
     post:
@@ -1849,24 +1861,30 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+              example: *id008
         '401':
           description: Invalid user
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+              example: *id009
         '500':
           description: Internal server error
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+              example: *id010
         '507':
           description: Not enough disk space
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+              example:
+                code: 507
+                message: 'Insufficient storage: not enough disk space'
         '502': *id003
       operationId: uploadFile
     servers:
@@ -2064,36 +2082,46 @@ components:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
+          example: *id008
     '401':
       description: Authentication error
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
+          example: *id009
     '403':
       description: Forbidden
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
+          example:
+            code: 403
+            message: 'Forbidden: insufficient permissions'
     '404':
       description: Not found
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
+          example: *id011
     '409':
       description: Conflict
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
+          example:
+            code: 409
+            message: 'Conflict: the resource is in a conflicting state'
     '500':
       description: Server error
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
+          example: *id010
   schemas:
     Error:
       required:
@@ -2108,9 +2136,6 @@ components:
           type: string
           description: Error
       type: object
-      example:
-        code: 400
-        message: 'Bad request: invalid or missing request parameters'
     EntryInfo:
       required:
       - path

scripts/generate_openapi_reference.py

@@ -1022,14 +1022,45 @@ def _singularize(word: str) -> str:
             responses["500"] = {"$ref": "#/components/responses/500"}
             fixes.append("/sandboxes/{sandboxID}/refreshes: added 500 response")
 
-    # 25. Add meaningful example to the Error schema (applies everywhere it's referenced)
-    error_schema = schemas.get("Error")
-    if error_schema and "example" not in error_schema:
-        error_schema["example"] = {
-            "code": 400,
-            "message": "Bad request: invalid or missing request parameters",
-        }
-        fixes.append("Error schema: added example values")
+    # 25. Add per-status error examples to every error response in every operation
+    status_examples = {
+        "400": {"code": 400, "message": "Bad request: invalid or missing request parameters"},
+        "401": {"code": 401, "message": "Authentication error: missing or invalid API key"},
+        "403": {"code": 403, "message": "Forbidden: insufficient permissions"},
+        "404": {"code": 404, "message": "Not found: the requested resource does not exist"},
+        "409": {"code": 409, "message": "Conflict: the resource is in a conflicting state"},
+        "500": {"code": 500, "message": "Server error: an unexpected error occurred"},
+        "507": {"code": 507, "message": "Insufficient storage: not enough disk space"},
+    }
+    for path_item in spec.get("paths", {}).values():
+        for method in ("get", "post", "put", "patch", "delete", "head", "options"):
+            op = path_item.get(method)
+            if not op:
+                continue
+            for status_code, resp in op.get("responses", {}).items():
+                if not isinstance(resp, dict) or "$ref" in resp:
+                    continue
+                example = status_examples.get(str(status_code))
+                if not example:
+                    continue
+                json_media = resp.get("content", {}).get("application/json")
+                if not json_media:
+                    continue
+                schema = json_media.get("schema", {})
+                # Only add example if schema references Error
+                ref = schema.get("$ref", "")
+                if ref.endswith("/Error") and "example" not in json_media:
+                    json_media["example"] = example
+    # Also set examples on component-level responses
+    comp_responses = spec.get("components", {}).get("responses", {})
+    for status_code, example in status_examples.items():
+        resp = comp_responses.get(status_code)
+        if not resp or "content" not in resp:
+            continue
+        json_media = resp["content"].get("application/json")
+        if json_media and "example" not in json_media:
+            json_media["example"] = example
+    fixes.append("Error responses: added per-status example values")
 
     if fixes:
         print(f"==> Fixed {len(fixes)} spec issues:")