feat(api-docs): Redoc-rendered /api/docs + consolidate OpenAPI spec to docs/openapi.yaml (#4781)

Redoc /api/docs + OpenAPI spec consolidated to docs/openapi.yaml (canonical 201-path complete spec; old path → legacy fallback). All refs/gates/tests/CI updated. Integrated into release/v3.8.35.

.github/workflows/ci.yml

@@ -227,7 +227,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       # fetch-depth: 0 — the OpenAPI breaking-change gate (oasdiff) reads the base
-      # spec via `git show <base_ref>:docs/reference/openapi.yaml`; a shallow clone
+      # spec via `git show <base_ref>:docs/openapi.yaml`; a shallow clone
       # would lack the base ref and the gate would self-skip (base-unresolved).
       - uses: actions/checkout@v7
         with:
@@ -318,7 +318,7 @@ jobs:
       - name: Workflow lint (actionlint+zizmor, ratchet, blocking)
         run: npm run check:workflows -- --ratchet
       # OpenAPI breaking-change detection (oasdiff). Diffs the PR's public API
-      # contract (docs/reference/openapi.yaml) against the base branch's spec.
+      # contract (docs/openapi.yaml) against the base branch's spec.
       # BLOCKING ratchet (Fase 9 Onda 0): reads metrics.openapiBreaking.value and
       # exits 1 ONLY on a measured regression (count > baseline). It SKIPs (exit 0)
       # when oasdiff is absent or the base spec can't be resolved — a missing

.github/workflows/dast-smoke.yml

@@ -42,7 +42,7 @@ jobs:
       - run: pip install schemathesis
       - name: Schemathesis smoke (high-risk endpoints, blocking)
         run: |
-          schemathesis run docs/reference/openapi.yaml --url http://localhost:20128 \
+          schemathesis run docs/openapi.yaml --url http://localhost:20128 \
             --include-path-regex '^/v1/(chat/completions|models)$|^/api/(auth|keys)' \
             --max-examples 8 --workers 4 --checks all --max-response-time 30 \
             --request-timeout 20 --suppress-health-check all --no-color

.github/workflows/nightly-schemathesis.yml

@@ -45,7 +45,7 @@ jobs:
         # PROVE the contract is fuzzable and surface regressions, not to gate the build.
         continue-on-error: true
         run: |
-          schemathesis run docs/reference/openapi.yaml \
+          schemathesis run docs/openapi.yaml \
             --url http://localhost:20128 \
             --max-examples 20 \
             --workers 4 \