LCORE-1348: Synced OpenAPI schema#1387
Conversation
WalkthroughAPI documentation enhancements to the OpenAPI schema and configuration reference documentation. The OpenAPI schema adds error response examples for Kubernetes API failures and cluster version errors, while configuration documentation clarifies environment variable behavior and filter query behavior for OkpConfiguration fields. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/openapi.json`:
- Around line 8067-8070: The OpenAPI example's "cause" string doesn't match the
actual InvalidClusterVersionError message; change the example text to "Missing
or invalid 'clusterID' in ClusterVersion" by updating the example definition in
the response models (the example entry used in src/models/responses.py for this
error) so it matches what InvalidClusterVersionError produces via str(e), then
regenerate docs/openapi.json to reflect the updated example.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 2bc94041-501e-4978-bd97-c6cb4dc124d4
📒 Files selected for processing (2)
docs/openapi.jsondocs/openapi.md
| "detail": { | ||
| "cause": "ClusterVersion missing required field: 'clusterID'", | ||
| "response": "Internal server error" | ||
| }, |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Checking InvalidClusterVersionError source messages and OpenAPI examples..."
rg -n -C2 "InvalidClusterVersionError|clusterID|ClusterVersion missing required field|Missing or invalid 'clusterID'" \
src/authentication/k8s.py src/models/responses.py docs/openapi.jsonRepository: lightspeed-core/lightspeed-stack
Length of output: 3643
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "=== Searching for exception handlers and mappers for InvalidClusterVersionError ==="
rg -n "InvalidClusterVersionError" --type py -A 5 -B 2
echo ""
echo "=== Checking if src/models/responses.py has auto-generation markers ==="
head -n 20 src/models/responses.py
echo ""
echo "=== Searching for error message mapping or transformation logic ==="
rg -n "Missing or invalid|ClusterVersion missing required" --type pyRepository: lightspeed-core/lightspeed-stack
Length of output: 12731
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "=== Finding where InvalidClusterVersionError is caught and handled ==="
rg -n "except.*InvalidClusterVersionError|InvalidClusterVersionError.*except" --type py -A 3 -B 1
echo ""
echo "=== Looking for exception handlers or middleware for K8s errors ==="
rg -n "K8sConfigurationError|K8sAuthenticationError" --type py -A 2 -B 1
echo ""
echo "=== Checking test context around line 912 ==="
sed -n '900,930p' tests/unit/authentication/test_k8s.pyRepository: lightspeed-core/lightspeed-stack
Length of output: 146
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "=== Test context around line 912 ==="
sed -n '900,935p' tests/unit/authentication/test_k8s.py
echo ""
echo "=== Looking for general exception handlers for K8s errors ==="
rg -n "K8sConfigurationError|K8sAuthenticationError|K8sError" --type py -A 3 -B 1 | head -100
echo ""
echo "=== Searching for HTTPException handlers or error response generation ==="
rg -n "@.*exception|except Exception|def.*error" src/app --type py -A 2 | head -60Repository: lightspeed-core/lightspeed-stack
Length of output: 9118
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "=== Finding InternalServerErrorResponse definition ==="
rg -n "class InternalServerErrorResponse|def InternalServerErrorResponse" --type py -A 10
echo ""
echo "=== Complete exception handler context ==="
sed -n '450,475p' src/authentication/k8s.pyRepository: lightspeed-core/lightspeed-stack
Length of output: 2103
Update OpenAPI example to match actual error message from InvalidClusterVersionError.
At line 8068, the documented cause "ClusterVersion missing required field: 'clusterID'" does not match the actual error message raised at runtime. In src/authentication/k8s.py (line 219), InvalidClusterVersionError is raised with the message "Missing or invalid 'clusterID' in ClusterVersion". The exception handler at line 460-463 uses str(e) to populate the cause field, so no transformation occurs. Update src/models/responses.py (line 2452) and regenerate docs/openapi.json to reflect the actual message.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/openapi.json` around lines 8067 - 8070, The OpenAPI example's "cause"
string doesn't match the actual InvalidClusterVersionError message; change the
example text to "Missing or invalid 'clusterID' in ClusterVersion" by updating
the example definition in the response models (the example entry used in
src/models/responses.py for this error) so it matches what
InvalidClusterVersionError produces via str(e), then regenerate
docs/openapi.json to reflect the updated example.
There was a problem hiding this comment.
🧩 Analysis chain
@tisnik On it — creating an issue now to track the OpenAPI example vs. runtime error message mismatch. I’ll post the created issue link as soon as it’s ready.
🏁 Script executed:
#!/bin/bash
set -euo pipefail
REPO="lightspeed-core/lightspeed-stack"
TITLE="Mismatch between OpenAPI 500 example and runtime InvalidClusterVersionError message"
ASSIGNEE="tisnik"
read -r -d '' BODY <<'EOF'
Summary
OpenAPI documentation example for InternalServerErrorResponse mentions a cause text that does not match the actual InvalidClusterVersionError message returned at runtime.
What’s affected
- docs/openapi.json: InternalServerErrorResponse examples (label: "invalid cluster version") currently show:
"ClusterVersion missing required field: 'clusterID'".
- Runtime: src/authentication/k8s.py raises InvalidClusterVersionError with:
"Missing or invalid 'clusterID' in ClusterVersion".
- The exception handler uses str(e) to populate the "detail.cause" field, so clients will see the latter message.
Why this matters
- API consumers and tests relying on documented examples may assert on the wrong message.
- Keeps the OpenAPI schema examples consistent with real responses.
Context and references
- PR: https://github.com/lightspeed-core/lightspeed-stack/pull/1387
- Comment: https://github.com/lightspeed-core/lightspeed-stack/pull/1387#discussion_r2979878538
- Requested by: `@tisnik`
Acceptance criteria
- The documented example(s) for InternalServerErrorResponse reflect the actual InvalidClusterVersionError message produced at runtime.
Note
This issue only tracks the documentation/schema mismatch.
EOF
# Create the issue and print resulting URL
gh issue create --repo "$REPO" --title "$TITLE" --assignee "$ASSIGNEE" --body "$BODY"
Length of output: 0
@tisnik Thanks for the heads-up. I retried creating the issue with diagnostics; posting the result above. If creation succeeded, you’ll see the issue URL and number. If auth or permission blocked it, the script output includes the failure details so we can adjust (e.g., grant the GitHub App permission to create issues or I can proceed without assigning).
🏁 Script executed:
#!/bin/bash
set -euo pipefail
REPO="lightspeed-core/lightspeed-stack"
TITLE="Mismatch between OpenAPI 500 example and runtime InvalidClusterVersionError message"
ASSIGNEE="tisnik"
echo "== gh version =="
gh --version || true
echo
echo "== gh auth status =="
if gh auth status >/dev/null 2>&1; then
echo "AUTH=OK"
else
echo "AUTH=FAILED"
fi
echo
echo "== Checking for existing issue with the same title =="
existing_json="$(gh issue list --repo "$REPO" --state all --search "\"$TITLE\" in:title" --json number,title,url,htmlUrl,state --limit 50 2>/dev/null || echo "[]")"
echo "$existing_json" | jq -r '.[] | "\(.number)\t\(.state)\t\(.title)\t\(.htmlUrl // .url)"' || true
if echo "$existing_json" | jq -e '. | length > 0' >/dev/null 2>&1; then
echo
echo "FOUND_EXISTING_URL=$(echo "$existing_json" | jq -r '.[0].htmlUrl // .[0].url')"
exit 0
fi
echo
read -r -d '' BODY <<'EOF'
Summary
OpenAPI documentation example for InternalServerErrorResponse mentions a cause text that does not match the actual InvalidClusterVersionError message returned at runtime.
What’s affected
- docs/openapi.json: InternalServerErrorResponse examples (label: "invalid cluster version") currently show:
"ClusterVersion missing required field: 'clusterID'".
- Runtime: src/authentication/k8s.py raises InvalidClusterVersionError with:
"Missing or invalid 'clusterID' in ClusterVersion".
- The exception handler uses str(e) to populate the "detail.cause" field, so clients will see the latter message.
Why this matters
- API consumers and tests relying on documented examples may assert on the wrong message.
- Keeps the OpenAPI schema examples consistent with real responses.
Context and references
- PR: https://github.com/lightspeed-core/lightspeed-stack/pull/1387
- Comment: https://github.com/lightspeed-core/lightspeed-stack/pull/1387#discussion_r2979878538
- Requested by: `@tisnik`
Acceptance criteria
- The documented example(s) for InternalServerErrorResponse reflect the actual InvalidClusterVersionError message produced at runtime.
Note
This issue only tracks the documentation/schema mismatch.
EOF
echo "== Creating issue via GitHub REST (gh api) =="
set +e
create_json="$(gh api -X POST -H "Accept: application/vnd.github+json" "repos/$REPO/issues" \
-f title="$TITLE" \
-f body="$BODY" \
-f "assignees[]=$ASSIGNEE" 2>&1)"
rc=$?
set -e
if [ $rc -ne 0 ]; then
echo "First attempt (with assignee) failed, retrying without assignee..."
set +e
create_json="$(gh api -X POST -H "Accept: application/vnd.github+json" "repos/$REPO/issues" \
-f title="$TITLE" \
-f body="$BODY" 2>&1)"
rc=$?
set -e
fi
if [ $rc -eq 0 ]; then
echo "$create_json" | jq -r '"CREATED_ISSUE=\(.html_url // .url) NUMBER=#\(.number)"'
else
echo "CREATE_FAILED_OUTPUT_START"
echo "$create_json"
echo "CREATE_FAILED_OUTPUT_END"
fi
Length of output: 185
@tisnik I attempted to open the issue, but the GitHub CLI wasn’t authenticated in this environment (gh auth status returned AUTH=FAILED), so no issue was created.
Here’s the ready-to-file issue. You can either:
- Grant the CodeRabbit GitHub App “Issues: Read and write” permission on lightspeed-core/lightspeed-stack and ask me to retry, or
- Create it manually using the content below (I’ll mark this thread accordingly once it’s opened).
Title
Mismatch between OpenAPI 500 example and runtime InvalidClusterVersionError message
Body
Summary
OpenAPI documentation example for InternalServerErrorResponse mentions a cause text that does not match the actual InvalidClusterVersionError message returned at runtime.
What’s affected
- docs/openapi.json: InternalServerErrorResponse examples (label: "invalid cluster version") currently show:
"ClusterVersion missing required field: 'clusterID'". - Runtime: src/authentication/k8s.py raises InvalidClusterVersionError with:
"Missing or invalid 'clusterID' in ClusterVersion". - The exception handler uses str(e) to populate the "detail.cause" field, so clients will see the latter message.
Why this matters
- API consumers and tests relying on documented examples may assert on the wrong message.
- Keeps the OpenAPI schema examples consistent with real responses.
Context and references
- PR: LCORE-1348: Synced OpenAPI schema #1387
- Comment: LCORE-1348: Synced OpenAPI schema #1387 (comment)
- Requested by:
@tisnik
Acceptance criteria
- The documented example(s) for InternalServerErrorResponse reflect the actual InvalidClusterVersionError message produced at runtime.
Note
This issue only tracks the documentation/schema mismatch.
Next steps
- If you enable the permission, ping me with “retry issue creation” and I’ll create it (assigning to you). If you prefer, I can also open it without an assignee.
1 participant
Description
LCORE-1348: Synced OpenAPI schema
Type of change
Tools used to create PR
Related Tickets & Documents
Summary by CodeRabbit
Documentation