LCORE-632: updated OpenAPI documentation #783
Conversation
WalkthroughThe pull request updates OpenAPI documentation across two files, revising endpoint descriptions, error messages, and response definitions. It introduces a new /v2/query endpoint and adds comprehensive documentation for error response types including quota exceeded, access denied, bad request, and not found responses. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes
Possibly related PRs
Suggested labels
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ 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: 4
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
docs/openapi.md(23 hunks)docs/output.md(23 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/openapi.md
[grammar] ~203-~203: Use a hyphen to join words.
Context: ...handler_base that provides the Agent API specific retrieve_response and get_topic...
(QB_NEW_EN_HYPHEN)
[grammar] ~567-~567: Use a hyphen to join words.
Context: ...ler_base that provides the Responses API specific retrieve_response and get_topic...
(QB_NEW_EN_HYPHEN)
docs/output.md
[grammar] ~203-~203: Use a hyphen to join words.
Context: ...handler_base that provides the Agent API specific retrieve_response and get_topic...
(QB_NEW_EN_HYPHEN)
[grammar] ~567-~567: Use a hyphen to join words.
Context: ...ler_base that provides the Responses API specific retrieve_response and get_topic...
(QB_NEW_EN_HYPHEN)
🪛 markdownlint-cli2 (0.18.1)
docs/openapi.md
348-348: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
394-394: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
589-589: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
⏰ 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). (4)
- GitHub Check: build-pr
- GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-on-pull-request
- GitHub Check: e2e_tests (ci)
- GitHub Check: e2e_tests (azure)
🔇 Additional comments (6)
docs/openapi.md (5)
222-223: Enhanced error handling documentation for/v1/queryendpoint.The addition of 403 (Forbidden) and 429 (Quota Exceeded) responses with specific component references improves API contract clarity. The error descriptions align with their HTTP semantics.
263-264: Enhanced error handling documentation for/v1/streaming_queryendpoint.Consistent with
/v1/query, the 403 and 429 responses are properly documented here, maintaining API consistency across query endpoints.
560-589: New/v2/queryendpoint properly documented.The v2 endpoint is well-structured and mirrors v1 semantics appropriately. The description correctly identifies it as wrapping
query_endpoint_handler_basewith Responses API-specific behavior. Note: Apply the "API-specific" hyphenation fix mentioned earlier at lines 564-567.
680-689: New error response components are well-structured.The addition of
AccessDeniedResponse,BadRequestResponse,NotFoundResponse,QuotaExceededResponse, andServiceUnavailableResponseprovides clear, reusable models for API error handling. Each component properly documents the HTTP status, semantics, and field structure. The newDetailModelsupports nested error details. This design supports comprehensive error documentation across the API.Also applies to: 783-792, 1118-1128, 1430-1439, 1567-1576, 1710-1719
844-844: Configuration extended with quota handling.The addition of
quota_handlersfield to theConfigurationcomponent indicates support for quota management. Ensure the related configuration models (QuotaHandlersConfiguration,QuotaLimiterConfiguration,QuotaSchedulerConfiguration) are properly implemented in the backend.Can you verify that the backend code implements the quota handlers referenced in this configuration model? Please confirm this is not a documentation-only change.
docs/output.md (1)
1-1: Verify whether docs/openapi.md and docs/output.md should remain identical.Both files contain identical content and changes. If they're meant to serve different purposes (e.g., one as source and one as generated output), clarify the relationship. If intentional duplication, confirm both will be kept in sync going forward.
Are these files intentionally duplicated, or should they be consolidated into a single source with a build step to generate the output file?
| Handle request to the /query endpoint using Agent API. | ||
|
|
||
| Processes a POST request to the /query endpoint, forwarding the | ||
| user's query to a selected Llama Stack LLM or agent and | ||
| returning the generated response. | ||
|
|
||
| Validates configuration and authentication, selects the appropriate model | ||
| and provider, retrieves the LLM response, updates metrics, and optionally | ||
| stores a transcript of the interaction. Handles connection errors to the | ||
| Llama Stack service by returning an HTTP 500 error. | ||
| This is a wrapper around query_endpoint_handler_base that provides | ||
| the Agent API specific retrieve_response and get_topic_summary functions. |
There was a problem hiding this comment.
Fix hyphenation in compound modifiers.
"API specific" should use a hyphen: "API-specific" when used as a compound modifier before a noun. This applies to both "Agent API-specific" and "Responses API-specific" in similar sections.
- Handle request to the /query endpoint using Agent API.
+ Handle request to the /query endpoint using Agent API.
- This is a wrapper around query_endpoint_handler_base that provides
- the Agent API specific retrieve_response and get_topic_summary functions.
+ This is a wrapper around query_endpoint_handler_base that provides
+ the Agent API-specific retrieve_response and get_topic_summary functions.📝 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.
| Handle request to the /query endpoint using Agent API. | |
| Processes a POST request to the /query endpoint, forwarding the | |
| user's query to a selected Llama Stack LLM or agent and | |
| returning the generated response. | |
| Validates configuration and authentication, selects the appropriate model | |
| and provider, retrieves the LLM response, updates metrics, and optionally | |
| stores a transcript of the interaction. Handles connection errors to the | |
| Llama Stack service by returning an HTTP 500 error. | |
| This is a wrapper around query_endpoint_handler_base that provides | |
| the Agent API specific retrieve_response and get_topic_summary functions. | |
| Handle request to the /query endpoint using Agent API. | |
| This is a wrapper around query_endpoint_handler_base that provides | |
| the Agent API-specific retrieve_response and get_topic_summary functions. |
🧰 Tools
🪛 LanguageTool
[grammar] ~203-~203: Use a hyphen to join words.
Context: ...handler_base that provides the Agent API specific retrieve_response and get_topic...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
docs/openapi.md around lines 200 to 203: the phrase "Agent API specific" is
missing the hyphen for a compound modifier; update this and any similar
occurrences (e.g., "Responses API-specific") to use "API-specific" when
appearing before a noun. Search the document for "API specific" and replace with
"API-specific" in all compound-modifier contexts, preserving spacing and
punctuation.
| | Status Code | Description | Component | | ||
| |-------------|-------------|-----------| | ||
| | 200 | Successful Response | [StatusResponse](#statusresponse) | | ||
| | 200 | Feedback status successfully retrieved | [StatusResponse](#statusresponse) | |
There was a problem hiding this comment.
Add blank lines around Markdown tables.
Per MD058, tables should be surrounded by blank lines. Insert a blank line before and after the response tables at these locations to ensure proper Markdown rendering and linting compliance.
Example fix for line 348:
Returns:
StatusResponse: Indicates whether feedback collection is enabled.
+
### ✅ Responses
| Status Code | Description | Component |Also applies to: 394-394, 589-589
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
348-348: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In docs/openapi.md around lines 348, 394, and 589, the Markdown tables are not
surrounded by blank lines which violates MD058; insert a single blank line
immediately before and immediately after each table block (i.e., add an empty
line above the table header line and another empty line after the final table
row) so the response tables at those locations are separated from surrounding
text and render/lint correctly.
| Handle request to the /query endpoint using Agent API. | ||
|
|
||
| Processes a POST request to the /query endpoint, forwarding the | ||
| user's query to a selected Llama Stack LLM or agent and | ||
| returning the generated response. | ||
|
|
||
| Validates configuration and authentication, selects the appropriate model | ||
| and provider, retrieves the LLM response, updates metrics, and optionally | ||
| stores a transcript of the interaction. Handles connection errors to the | ||
| Llama Stack service by returning an HTTP 500 error. | ||
| This is a wrapper around query_endpoint_handler_base that provides | ||
| the Agent API specific retrieve_response and get_topic_summary functions. |
There was a problem hiding this comment.
Fix hyphenation in compound modifiers (same as docs/openapi.md).
Both /v1/query and /v2/query endpoint descriptions use "API specific" which should be "API-specific" as a compound modifier. Apply the same hyphenation fix in this file as needed for docs/openapi.md.
Also applies to: 564-567
🧰 Tools
🪛 LanguageTool
[grammar] ~203-~203: Use a hyphen to join words.
Context: ...handler_base that provides the Agent API specific retrieve_response and get_topic...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In docs/output.md around lines 200-203 and again around lines 564-567, replace
the unhyphenated phrase "API specific" with the correctly hyphenated compound
modifier "API-specific" in the endpoint descriptions for /v1/query and
/v2/query; update both occurrences so the wording reads "Agent API-specific
retrieve_response and get_topic_summary functions" (or the equivalent
surrounding phrase) to match docs/openapi.md.
| | Status Code | Description | Component | | ||
| |-------------|-------------|-----------| | ||
| | 200 | Successful Response | [StatusResponse](#statusresponse) | | ||
| | 200 | Feedback status successfully retrieved | [StatusResponse](#statusresponse) | |
There was a problem hiding this comment.
Add blank lines around Markdown tables (same as docs/openapi.md).
Per MD058 linting rule, add blank lines before and after tables at these line ranges in this file as well.
Also applies to: 394-394, 589-589
🤖 Prompt for AI Agents
In docs/output.md around lines 348, 394, and 589, the markdown tables lack blank
lines before and after them which violates MD058; insert a single blank line
immediately before each table start and a single blank line immediately after
each table end so the tables are separated from surrounding paragraphs and
headings, matching the formatting used in docs/openapi.md.
1 participant
Description
LCORE-632: updated OpenAPI documentation
Type of change
Related Tickets & Documents
Summary by CodeRabbit
New Features
Documentation