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

@@ -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

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:

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