LCORE-433: Fixed OpenAPI documentation formatting #386
Conversation
WalkthroughMarkdown table rows in docs/openapi.md were corrected across multiple endpoint response sections: empty pipe-only rows were removed and replaced with rows listing the appropriate Component references. Minor alignment and closure fixes were applied. No endpoints, schemas, or logic changed. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related PRs
Poem
✨ Finishing Touches🧪 Generate unit tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (7)
docs/openapi.md (7)
110-111: Clarify streaming response type instead of "..."Replace placeholder "..." with a clear indication of the streaming media type or a component name. If you don’t want to introduce a new component, explicitly note SSE:
-| 200 | Successful Response | ... | +| 200 | Successful Response | text/event-stream (SSE) |Alternatively, define and reference a "StreamingChunk" component if you document event payloads elsewhere.
111-111: Add missing blank line after table (MD058)The table should be followed by a blank line.
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | + ## GET `/v1/config`
184-184: Add missing blank line after table (MD058)Satisfy markdownlint by adding a blank line.
| 200 | Successful Response | [StatusResponse](#statusresponse) | + ## GET `/v1/conversations`
199-199: Fill missing 503 component for conversations listKeep error response shape consistent.
| 200 | Successful Response | [ConversationsListResponse](#conversationslistresponse) | -| 503 | Service Unavailable | | +| 503 | Service Unavailable | [ErrorResponse](#errorresponse) |
265-266: Add missing blank line after table (MD058)Add a blank line after the table.
| 200 | Service is ready | [ReadinessResponse](#readinessresponse) | | 503 | Service is not ready | [ReadinessResponse](#readinessresponse) | + ## GET `/liveness`
284-285: Add missing blank line after table (MD058)Add a blank line after the table.
| 200 | Service is alive | [LivenessResponse](#livenessresponse) | | 503 | Service is not alive | [LivenessResponse](#livenessresponse) | + ## POST `/authorized`
306-308: Add missing blank line after table (MD058)Add a blank line after the table.
| 200 | The user is logged-in and authorized to access OLS | [AuthorizedResponse](#authorizedresponse) | | 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) | | 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) | + ## GET `/metrics`
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/openapi.md(13 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
docs/openapi.md
91-91: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
111-111: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
166-166: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
184-184: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
223-223: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
246-246: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
266-266: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
285-285: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
308-308: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🪛 LanguageTool
docs/openapi.md
[style] ~165-~165: Unless you want to emphasize “not”, use “cannot” which is more common.
Context: ...biddenresponse) | | 500 | User feedback can not be stored | [ErrorResponse](#errorrespo...
(CAN_NOT_PREMIUM)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: e2e_tests
🔇 Additional comments (1)
docs/openapi.md (1)
1030-1030: LGTM: trailing newline at EOFAdding/keeping a trailing newline at EOF is a good practice and avoids tooling diffs.
| | 200 | Successful Response | [ModelsResponse](#modelsresponse) | | ||
| | 503 | Connection to Llama Stack is broken | | | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Fill missing 503 component for consistency
The 503 row has an empty Component. Recommend referencing a common error schema for consistency across endpoints.
Apply:
-| 503 | Connection to Llama Stack is broken | |
+| 503 | Connection to Llama Stack is broken | [ErrorResponse](#errorresponse) |
+📝 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.
| | 200 | Successful Response | [ModelsResponse](#modelsresponse) | | |
| | 503 | Connection to Llama Stack is broken | | | |
| | 200 | Successful Response | [ModelsResponse](#modelsresponse) | | |
| | 503 | Connection to Llama Stack is broken | [ErrorResponse](#errorresponse) | |
🤖 Prompt for AI Agents
In docs/openapi.md around lines 66 to 68, the 503 row has an empty Component;
update that table row to reference the shared error schema (e.g., replace the
empty cell with [ErrorResponse](#errorresponse) or the project’s canonical error
component name) so the 503 response points to the common error definition and
matches other endpoints; ensure the referenced component anchor exists or add a
matching ErrorResponse component if missing.
| | 200 | Successful Response | [QueryResponse](#queryresponse) | | ||
| | 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) | | ||
| | 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) | | ||
| | 503 | Service Unavailable | | | ||
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | ||
| | | ||
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | | ||
| ## POST `/v1/streaming_query` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add missing blank line after table (MD058) and fill 503 component
- markdownlint MD058: tables should be surrounded by blank lines — add one after the table.
- Keep response tables consistent by defining the 503 component.
| 200 | Successful Response | [QueryResponse](#queryresponse) |
| 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
| 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) |
-| 503 | Service Unavailable | |
+| 503 | Service Unavailable | [ErrorResponse](#errorresponse) |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
+
## POST `/v1/streaming_query`📝 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.
| | 200 | Successful Response | [QueryResponse](#queryresponse) | | |
| | 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) | | |
| | 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) | | |
| | 503 | Service Unavailable | | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | |
| | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | | |
| ## POST `/v1/streaming_query` | |
| | 200 | Successful Response | [QueryResponse](#queryresponse) | | |
| | 400 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) | | |
| | 403 | User is not authorized | [ForbiddenResponse](#forbiddenresponse) | | |
| | 503 | Service Unavailable | [ErrorResponse](#errorresponse) | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | | |
| ## POST `/v1/streaming_query` |
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
91-91: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In docs/openapi.md around lines 87 to 92, the response table lacks a trailing
blank line and the 503 status has no referenced response component; add a blank
line after the table to satisfy MD058 and update the 503 row to reference an
existing or new response component (e.g.,
[ServiceUnavailableResponse](#serviceunavailableresponse)), then add the
corresponding 503 component definition in the responses/components section (or
reuse an appropriate existing response schema) so the table remains consistent.
| |-------------|-------------|-----------| | ||
| | 200 | Successful Response | [Configuration](#configuration) | ||
| | | ||
| | 200 | Successful Response | [Configuration](#configuration) | |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Fill missing 503 component and add blank line after table (MD058)
Bring this in line with other endpoints and satisfy markdownlint.
| 200 | Successful Response | [Configuration](#configuration) |
-| 503 | Service Unavailable | |
+| 503 | Service Unavailable | [ErrorResponse](#errorresponse) |
+
## POST `/v1/feedback`📝 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.
| | 200 | Successful Response | [Configuration](#configuration) | | |
| | 200 | Successful Response | [Configuration](#configuration) | | |
| | 503 | Service Unavailable | [ErrorResponse](#errorresponse) | | |
| ## POST `/v1/feedback` |
🤖 Prompt for AI Agents
In docs/openapi.md around line 132, the response table currently lists only the
200 response and is missing the 503 component and a blank line after the table;
update the table to include a 503 | Service Unavailable | [Error](#error) (or
the appropriate Error/ServiceUnavailable component used elsewhere) row to match
other endpoints, then insert a single blank line immediately after the table so
markdownlint rule MD058 is satisfied.
| | 200 | Feedback received and stored | [FeedbackResponse](#feedbackresponse) | | ||
| | 401 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) | | ||
| | 403 | Client does not have permission to access resource | [ForbiddenResponse](#forbiddenresponse) | | ||
| | 500 | User feedback can not be stored | [ErrorResponse](#errorresponse) | | ||
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Grammar fix (“cannot”) and add blank line after table (MD058)
- Use “cannot” (LanguageTool).
- Add blank line after the table.
| 200 | Feedback received and stored | [FeedbackResponse](#feedbackresponse) |
| 401 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) |
| 403 | Client does not have permission to access resource | [ForbiddenResponse](#forbiddenresponse) |
-| 500 | User feedback can not be stored | [ErrorResponse](#errorresponse) |
+| 500 | User feedback cannot be stored | [ErrorResponse](#errorresponse) |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
+
## GET `/v1/feedback/status`📝 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.
| | 200 | Feedback received and stored | [FeedbackResponse](#feedbackresponse) | | |
| | 401 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) | | |
| | 403 | Client does not have permission to access resource | [ForbiddenResponse](#forbiddenresponse) | | |
| | 500 | User feedback can not be stored | [ErrorResponse](#errorresponse) | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | | |
| | 200 | Feedback received and stored | [FeedbackResponse](#feedbackresponse) | | |
| | 401 | Missing or invalid credentials provided by client | [UnauthorizedResponse](#unauthorizedresponse) | | |
| | 403 | Client does not have permission to access resource | [ForbiddenResponse](#forbiddenresponse) | | |
| | 500 | User feedback cannot be stored | [ErrorResponse](#errorresponse) | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | | |
| ## GET `/v1/feedback/status` |
🧰 Tools
🪛 LanguageTool
[style] ~165-~165: Unless you want to emphasize “not”, use “cannot” which is more common.
Context: ...biddenresponse) | | 500 | User feedback can not be stored | [ErrorResponse](#errorrespo...
(CAN_NOT_PREMIUM)
🪛 markdownlint-cli2 (0.17.2)
166-166: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In docs/openapi.md around lines 162 to 166, the table entry uses "can not" and
the table is not followed by a blank line; update the text to use the correct
single-word form "cannot" for the 500 row ("User feedback cannot be stored") and
insert a blank line immediately after the table to satisfy the MD058 lint rule.
| | 200 | Successful Response | [ConversationResponse](#conversationresponse) | | ||
| | 404 | Not Found | | | ||
| | 503 | Service Unavailable | | | ||
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | ||
| | | ||
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | | ||
| ## DELETE `/v1/conversations/{conversation_id}` |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add missing components for 404/503 and blank line after table (MD058)
Recommend referencing a shared error response for Not Found and Service Unavailable, plus the required blank line.
| 200 | Successful Response | [ConversationResponse](#conversationresponse) |
-| 404 | Not Found | |
-| 503 | Service Unavailable | |
+| 404 | Not Found | [ErrorResponse](#errorresponse) |
+| 503 | Service Unavailable | [ErrorResponse](#errorresponse) |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
+
## DELETE `/v1/conversations/{conversation_id}`📝 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.
| | 200 | Successful Response | [ConversationResponse](#conversationresponse) | | |
| | 404 | Not Found | | | |
| | 503 | Service Unavailable | | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | |
| | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | | |
| ## DELETE `/v1/conversations/{conversation_id}` | |
| | 200 | Successful Response | [ConversationResponse](#conversationresponse) | | |
| | 404 | Not Found | [ErrorResponse](#errorresponse) | | |
| | 503 | Service Unavailable | [ErrorResponse](#errorresponse) | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | | |
| ## DELETE `/v1/conversations/{conversation_id}` |
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
223-223: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In docs/openapi.md around lines 220 to 224, the responses table omits component
references for the 404 and 503 responses and lacks the required blank line after
the table; update the table rows to reference a shared error response component
(e.g., [ErrorResponse](#errorresponse) or whatever shared error component name
is used elsewhere) for both 404 and 503, and add a single blank line after the
table before the "## DELETE `/v1/conversations/{conversation_id}`" heading.
| | 200 | Successful Response | [ConversationDeleteResponse](#conversationdeleteresponse) | | ||
| | 404 | Not Found | | | ||
| | 503 | Service Unavailable | | | ||
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | ||
| | | ||
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Add missing components for 404/503 and blank line after table (MD058)
Align with other sections and add required spacing.
| 200 | Successful Response | [ConversationDeleteResponse](#conversationdeleteresponse) |
-| 404 | Not Found | |
-| 503 | Service Unavailable | |
+| 404 | Not Found | [ErrorResponse](#errorresponse) |
+| 503 | Service Unavailable | [ErrorResponse](#errorresponse) |
| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) |
+
## GET `/readiness`📝 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.
| | 200 | Successful Response | [ConversationDeleteResponse](#conversationdeleteresponse) | | |
| | 404 | Not Found | | | |
| | 503 | Service Unavailable | | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | |
| | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | | |
| | 200 | Successful Response | [ConversationDeleteResponse](#conversationdeleteresponse) | | |
| | 404 | Not Found | [ErrorResponse](#errorresponse) | | |
| | 503 | Service Unavailable | [ErrorResponse](#errorresponse) | | |
| | 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | | |
| ## GET `/readiness` |
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
246-246: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In docs/openapi.md around lines 243-246, the responses table is missing
component links for the 404 and 503 rows and lacks the required blank line after
the table; update the table so 404 and 503 reference the appropriate component
schemas (e.g., [NotFoundResponse](#notfoundresponse) and
[ServiceUnavailableResponse](#serviceunavailableresponse) or whichever existing
component names are used elsewhere), and add a single blank line after the table
to satisfy MD058 and match other sections.
tisnik
changed the title
1 participant
Description
Fixed OpenAPI documentation formatting
Type of change
Summary by CodeRabbit