From 166f2de02980f1932b2cf6ac77b4e989053b1444 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Mon, 21 Sep 2026 23:55:40 +0000
Subject: [PATCH] fix(api): document 4xx and treat 302 as success in Redocly
 (DEV-289)

Health and CORS preflight document 400. Recommended only counted 2XX,
so login-style 302s use a shared 2XX-or-3XX rule.

Co-authored-by: Adam Moussa <amoussa1229@users.noreply.github.com>
---
 .redocly.yaml                    | 22 ++++++++++++++++++++++
 openapi.yaml                     |  4 ++++
 tests/infra/test_hcp_contract.py |  2 ++
 3 files changed, 28 insertions(+)

diff --git a/.redocly.yaml b/.redocly.yaml
index 7d19642..0914f58 100644
--- a/.redocly.yaml
+++ b/.redocly.yaml
@@ -1,7 +1,29 @@
 # Same Redocly recommended ruleset as internal-portal (DEV-223 / DEV-289).
+# Login-style redirects succeed with 302. Recommended only counts 2XX.
 extends:
   - recommended
 
+rules:
+  operation-2xx-response: off
+  rule/operation-2xx-or-3xx-response:
+    subject:
+      type: Responses
+    message: Operation must define a 2XX or 3XX response.
+    severity: warn
+    assertions:
+      requireAny:
+        - "200"
+        - "201"
+        - "202"
+        - "204"
+        - "301"
+        - "302"
+        - "303"
+        - "307"
+        - "308"
+        - "2XX"
+        - "3XX"
+
 apis:
   afterhours@v1:
     root: openapi.yaml
diff --git a/openapi.yaml b/openapi.yaml
index 5302e9c..d26e979 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -44,6 +44,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Health"
+        "400":
+          $ref: "#/components/responses/PortalError"
 
   /roster:
     put:
@@ -124,6 +126,8 @@ paths:
       responses:
         "204":
           description: Empty preflight
+        "400":
+          $ref: "#/components/responses/PortalError"
 
   /api/shifts/pick:
     post:
diff --git a/tests/infra/test_hcp_contract.py b/tests/infra/test_hcp_contract.py
index 0d80a67..8688ffd 100644
--- a/tests/infra/test_hcp_contract.py
+++ b/tests/infra/test_hcp_contract.py
@@ -130,6 +130,8 @@ def test_openapi_uses_redocly_recommended():
     spec = (ROOT / "openapi.yaml").read_text()
     assert "extends:" in redocly
     assert "- recommended" in redocly
+    assert "operation-2xx-response: off" in redocly
+    assert "rule/operation-2xx-or-3xx-response" in redocly
     assert 'root: openapi.yaml' in redocly
     assert '"openapi:lint"' in package
     assert '"@redocly/cli": "2.52.1"' in package