LCORE-1169: Up-to-date OpenAPI documentation #1019
Conversation
WalkthroughThese changes expand OpenAPI documentation by adding error response definitions (429 Quota Exceeded, 500 Internal Server Error), practical usage examples across models and endpoints, refined operation identifiers for A2A and streaming endpoints, and new configuration models for Azure Entra ID integration. The changes include new public entities and field type clarifications. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 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: 5
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/openapi.md (1)
1190-1194: Fix typo in validation error example (“attatchment”).This user-facing error message should read “attachment”. Please update all occurrences in the doc to keep examples consistent.
📝 Suggested fix
- "cause": "Invalid attatchment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']", + "cause": "Invalid attachment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']",
🤖 Fix all issues with AI agents
In `@docs/openapi.json`:
- Around line 4184-4187: The POST operationId "handle_a2a_jsonrpc_a2a_post"
conflicts with the GET operationId; make operationIds unique by renaming one
(e.g., keep "handle_a2a_jsonrpc_a2a_post" for POST and change the GET to
"handle_a2a_jsonrpc_a2a_get" or similar) in the OpenAPI spec (openapi.json) so
codegen tools won’t collide—update every reference to the renamed operationId
accordingly.
- Around line 6331-6334: The example in the description uses the wrong class
name; replace the `StatusResponse` instantiation with
`FeedbackStatusUpdateResponse` in the example block so it matches the schema
name `FeedbackStatusUpdateResponse` (update any related variable names or
references in that example if needed to maintain consistency).
- Around line 5726-5727: The Python example under the ConversationDetails schema
has a syntax error: add the missing comma after the conversation_id field in the
example instantiation of ConversationDetails so the tuple of keyword args is
valid (fix the example block that starts with conversation =
ConversationDetails(...), ensuring there is a comma after
conversation_id="123e4567-e89b-12d3-a456-426614174000").
In `@docs/openapi.md`:
- Around line 4203-4211: The ConversationDetails example has a missing comma
after the conversation_id field which makes the Python snippet invalid; update
the example for ConversationDetails by adding a trailing comma after the
conversation_id="123e4567-e89b-12d3-a456-426614174000" entry so the call to
ConversationDetails(...) is valid and the subsequent named arguments
(created_at, last_message_at, etc.) are parsed correctly.
- Around line 4500-4506: The example instantiates the wrong response type:
replace the StatusResponse construction with FeedbackStatusUpdateResponse so the
example matches the documented type; locate the example where status_response is
created and change the class name to FeedbackStatusUpdateResponse while keeping
the same payload keys ("previous_status", "updated_status", "updated_by",
"timestamp") so the variable status_response correctly reflects the
FeedbackStatusUpdateResponse type.
| "summary": "Handle A2A Jsonrpc", | ||
| "description": "Handle A2A JSON-RPC requests following the A2A protocol specification.\n\nThis endpoint uses the DefaultRequestHandler from the A2A SDK to handle\nall JSON-RPC requests including message/send, message/stream, etc.\n\nThe A2A SDK application is created per-request to include authentication\ncontext while still leveraging FastAPI's authorization middleware.\n\nAutomatically detects streaming requests (message/stream JSON-RPC method)\nand returns a StreamingResponse to enable real-time chunk delivery.\n\nArgs:\n request: FastAPI request object\n auth: Authentication tuple\n mcp_headers: MCP headers for context propagation\n\nReturns:\n JSON-RPC response or streaming response", | ||
| "operationId": "handle_a2a_jsonrpc_a2a_get", | ||
| "operationId": "handle_a2a_jsonrpc_a2a_post", | ||
| "responses": { |
There was a problem hiding this comment.
Ensure unique operationId for /a2a GET vs POST.
Line 4186 duplicates the POST operationId (Line 4204). OpenAPI tooling expects unique operationIds per operation, and codegen may collide.
🛠️ Proposed fix
- "operationId": "handle_a2a_jsonrpc_a2a_post",
+ "operationId": "handle_a2a_jsonrpc_a2a_get",Also applies to: 4199-4205
🤖 Prompt for AI Agents
In `@docs/openapi.json` around lines 4184 - 4187, The POST operationId
"handle_a2a_jsonrpc_a2a_post" conflicts with the GET operationId; make
operationIds unique by renaming one (e.g., keep "handle_a2a_jsonrpc_a2a_post"
for POST and change the GET to "handle_a2a_jsonrpc_a2a_get" or similar) in the
OpenAPI spec (openapi.json) so codegen tools won’t collide—update every
reference to the renamed operationId accordingly.
| "description": "Model representing the details of a user conversation.\n\nAttributes:\n conversation_id: The conversation ID (UUID).\n created_at: When the conversation was created.\n last_message_at: When the last message was sent.\n message_count: Number of user messages in the conversation.\n last_used_model: The last model used for the conversation.\n last_used_provider: The provider of the last used model.\n topic_summary: The topic summary for the conversation.\n\nExample:\n ```python\n conversation = ConversationDetails(\n conversation_id=\"123e4567-e89b-12d3-a456-426614174000\"\n created_at=\"2024-01-01T00:00:00Z\",\n last_message_at=\"2024-01-01T00:05:00Z\",\n message_count=5,\n last_used_model=\"gemini/gemini-2.0-flash\",\n last_used_provider=\"gemini\",\n topic_summary=\"Openshift Microservices Deployment Strategies\",\n )\n ```" | ||
| }, |
There was a problem hiding this comment.
Fix the Python example (missing comma).
Line 5726 is missing a comma after conversation_id, making the snippet invalid.
🛠️ Proposed fix
- conversation_id="123e4567-e89b-12d3-a456-426614174000"
+ conversation_id="123e4567-e89b-12d3-a456-426614174000",🤖 Prompt for AI Agents
In `@docs/openapi.json` around lines 5726 - 5727, The Python example under the
ConversationDetails schema has a syntax error: add the missing comma after the
conversation_id field in the example instantiation of ConversationDetails so the
tuple of keyword args is valid (fix the example block that starts with
conversation = ConversationDetails(...), ensuring there is a comma after
conversation_id="123e4567-e89b-12d3-a456-426614174000").
There was a problem hiding this comment.
🧩 Analysis chain
@tisnik Issue created. I’ve filed a tracking ticket for the invalid Python example under the ConversationDetails schema in docs/openapi.json, with backlinks to this PR and your comment, and assigned it to you. The URL is shown above in the run output.
🏁 Script executed:
#!/bin/bash
set -euo pipefail
REPO="lightspeed-core/lightspeed-stack"
TITLE="Docs: ConversationDetails example in docs/openapi.json is syntactically invalid (missing comma)"
BODY_FILE="$(mktemp)"
cat > "$BODY_FILE" << 'EOF'
Summary
The Python example embedded in the ConversationDetails schema description within docs/openapi.json is syntactically invalid due to a missing comma, causing the example snippet to be unparsable as written.
Where
- File: docs/openapi.json
- Component: components/schemas/ConversationDetails description "Example" block
- Context: This was identified during review of PR `#1019` (link below).
Impact
- The rendered documentation includes an invalid Python example, which could mislead users copying the snippet.
Requested action
- Update the example so it is valid Python syntax.
References
- PR: https://github.com/lightspeed-core/lightspeed-stack/pull/1019
- Review comment: https://github.com/lightspeed-core/lightspeed-stack/pull/1019#discussion_r2705524856
Requested by
- `@tisnik`
EOF
ISSUE_URL="$(gh issue create -R "$REPO" --title "$TITLE" --assignee "tisnik" --body-file "$BODY_FILE")"
echo "Created issue: $ISSUE_URL"
Length of output: 78
@tisnik Done — opened issue #1021 and assigned it to you. It includes backlinks to PR #1019 and this comment, plus a short summary of the missing comma in the ConversationDetails example within docs/openapi.json.
Would you like me to prep a quick follow-up to fix it in this PR, or keep it as a separate follow-up?
| "description": "Model representing a response to a feedback status update request.\n\nAttributes:\n status: The previous and current status of the service and who updated it.\n\nExample:\n ```python\n status_response = StatusResponse(\n status={\n \"previous_status\": true,\n \"updated_status\": false,\n \"updated_by\": \"user/test\",\n \"timestamp\": \"2023-03-15 12:34:56\"\n },\n )\n ```", | ||
| "examples": [ | ||
| { | ||
| "status": { |
There was a problem hiding this comment.
Correct the class name in the example.
Line 6331 uses StatusResponse instead of FeedbackStatusUpdateResponse.
🛠️ Proposed fix
- status_response = StatusResponse(
+ status_response = FeedbackStatusUpdateResponse(📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "description": "Model representing a response to a feedback status update request.\n\nAttributes:\n status: The previous and current status of the service and who updated it.\n\nExample:\n ```python\n status_response = StatusResponse(\n status={\n \"previous_status\": true,\n \"updated_status\": false,\n \"updated_by\": \"user/test\",\n \"timestamp\": \"2023-03-15 12:34:56\"\n },\n )\n ```", | |
| "examples": [ | |
| { | |
| "status": { | |
| "description": "Model representing a response to a feedback status update request.\n\nAttributes:\n status: The previous and current status of the service and who updated it.\n\nExample:\n |
🤖 Prompt for AI Agents
In `@docs/openapi.json` around lines 6331 - 6334, The example in the description
uses the wrong class name; replace the `StatusResponse` instantiation with
`FeedbackStatusUpdateResponse` in the example block so it matches the schema
name `FeedbackStatusUpdateResponse` (update any related variable names or
references in that example if needed to maintain consistency).
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
REPO="lightspeed-core/lightspeed-stack"
PR_URL="https://github.com/lightspeed-core/lightspeed-stack/pull/1019"
COMMENT_URL="https://github.com/lightspeed-core/lightspeed-stack/pull/1019#discussion_r2705524860"
TITLE="OpenAPI docs: Incorrect example class name in FeedbackStatusUpdateResponse"
cat > /tmp/issue_body.md <<'BODY'
Summary
The example in the description for the FeedbackStatusUpdateResponse schema uses the class name StatusResponse. This does not match the schema name and could confuse readers and downstream tooling.
Where
- File: docs/openapi.json
- Section: components.schemas.FeedbackStatusUpdateResponse.description (example block)
Impact
- Inconsistent example vs schema name; may mislead clients and documentation consumers.
Expected
- The example should reference FeedbackStatusUpdateResponse to match the schema.
Backlinks
- PR: https://github.com/lightspeed-core/lightspeed-stack/pull/1019
- Comment: https://github.com/lightspeed-core/lightspeed-stack/pull/1019#discussion_r2705524860
Requested by
- `@tisnik`
BODY
gh issue create -R "$REPO" --title "$TITLE" --body-file /tmp/issue_body.md --assignee "tisnik"
Length of output: 63
@tisnik Issue created: #1020 — OpenAPI docs: Incorrect example class name in FeedbackStatusUpdateResponse. It includes file location, impact, expected fix, and backlinks to this PR and your comment, and is assigned to you.
Would you like me to prepare a plan to update docs/openapi.json in this PR as well, or keep it for a follow-up PR tied to #1020?
| ```python | ||
| conversation = ConversationDetails( | ||
| conversation_id="123e4567-e89b-12d3-a456-426614174000" | ||
| created_at="2024-01-01T00:00:00Z", | ||
| last_message_at="2024-01-01T00:05:00Z", | ||
| message_count=5, | ||
| last_used_model="gemini/gemini-2.0-flash", | ||
| last_used_provider="gemini", | ||
| topic_summary="Openshift Microservices Deployment Strategies", |
There was a problem hiding this comment.
Fix missing comma in ConversationDetails example.
The example code is invalid Python as shown; add the trailing comma after conversation_id.
📝 Suggested fix
- conversation_id="123e4567-e89b-12d3-a456-426614174000"
+ conversation_id="123e4567-e89b-12d3-a456-426614174000",🤖 Prompt for AI Agents
In `@docs/openapi.md` around lines 4203 - 4211, The ConversationDetails example
has a missing comma after the conversation_id field which makes the Python
snippet invalid; update the example for ConversationDetails by adding a trailing
comma after the conversation_id="123e4567-e89b-12d3-a456-426614174000" entry so
the call to ConversationDetails(...) is valid and the subsequent named arguments
(created_at, last_message_at, etc.) are parsed correctly.
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Create GitHub issue for missing comma in ConversationDetails example
gh issue create \
--repo lightspeed-core/lightspeed-stack \
--title "Fix missing comma in ConversationDetails example documentation" \
--body "## Description
The Python example code for ConversationDetails in the OpenAPI documentation contains a syntax error - there is a missing comma after the conversation_id field, making the example invalid Python code.
## Location
- **File**: \`docs/openapi.md\`
- **Lines**: approximately 4203-4211
## Issue
The example shows:
\`\`\`python
conversation = ConversationDetails(
conversation_id=\"123e4567-e89b-12d3-a456-426614174000\"
created_at=\"2024-01-01T00:00:00Z\",
...
)
\`\`\`
The comma is missing after the \`conversation_id\` line, which would cause a syntax error if users try to use this example.
## Related
- Pull Request: https://github.com/lightspeed-core/lightspeed-stack/pull/1019
- Review Comment: https://github.com/lightspeed-core/lightspeed-stack/pull/1019#discussion_r2705524878
- Reported by: `@tisnik`" \
--assignee tisnik
Length of output: 63
@tisnik, I've created issue #1022 to track the missing comma in the ConversationDetails example documentation. The issue has been assigned to you and includes links back to this PR and review comment.
| ```python | ||
| status_response = StatusResponse( | ||
| status={ | ||
| "previous_status": true, | ||
| "updated_status": false, | ||
| "updated_by": "user/test", | ||
| "timestamp": "2023-03-15 12:34:56" |
There was a problem hiding this comment.
Use the correct response type in example.
This example is for FeedbackStatusUpdateResponse but instantiates StatusResponse, which is confusing.
📝 Suggested fix
- status_response = StatusResponse(
+ status_response = FeedbackStatusUpdateResponse(📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```python | |
| status_response = StatusResponse( | |
| status={ | |
| "previous_status": true, | |
| "updated_status": false, | |
| "updated_by": "user/test", | |
| "timestamp": "2023-03-15 12:34:56" |
🤖 Prompt for AI Agents
In `@docs/openapi.md` around lines 4500 - 4506, The example instantiates the wrong
response type: replace the StatusResponse construction with
FeedbackStatusUpdateResponse so the example matches the documented type; locate
the example where status_response is created and change the class name to
FeedbackStatusUpdateResponse while keeping the same payload keys
("previous_status", "updated_status", "updated_by", "timestamp") so the variable
status_response correctly reflects the FeedbackStatusUpdateResponse type.
1 participant
Description
LCORE-1169: Up-to-date OpenAPI documentation
Type of change
Tools used to create PR
Related Tickets & Documents
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.