LCORE-535: Regenerated OpenAPI schema #428
Conversation
WalkthroughAdds CORSConfiguration schema and integrates it into ServiceConfiguration in OpenAPI specs and docs. Enhances endpoint documentation (models, query, streaming_query, feedback, config), clarifies errors/returns, and tightens numeric validation with exclusiveMinimum on selected port/workers fields. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Client
participant API as Service API
participant Auth as Auth/Config
participant Router as Model Router
participant Llama as Llama Stack
participant Store as Metrics/Storage
rect rgba(230,245,255,0.6)
note over Client,API: POST /v1/query
Client->>API: QueryRequest
API->>Auth: Validate config/auth
Auth-->>API: OK or Error
API->>Router: Select model/provider
Router-->>API: Target model
API->>Llama: Invoke LLM
Llama-->>API: Response
API->>Store: Update metrics / optional transcript
Store-->>API: Ack
API-->>Client: QueryResponse
end
rect rgba(240,255,230,0.6)
note over Client,API: POST /v1/streaming_query (SSE)
Client->>API: StreamingQueryRequest
API->>Auth: Validate
Auth-->>API: OK or Error
API->>Router: Select model/provider
Router-->>API: Target model
API-)Llama: Start stream
Llama-)API: Tokens/events
loop Stream events
API--)Client: data: event chunk
end
API->>Store: Update metrics / optional transcript
API--)Client: [DONE] or error (HTTP 500 on connection failure)
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Poem
Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ 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: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/openapi.json (1)
699-2228: Critical: OpenAPI spec invalid—unexpectednameandversionproperties in response objectThe validation error indicates that in your
/v1/infoendpoint’s200response, you have top-level fieldsnameandversionwhich aren’t allowed by the OpenAPI 3.1 Response Object schema. These must be removed (or relocated under the response’scontent.schema) so that only the permitted keys (description,headers,content,links, plus any specification‐extensions) are present.• File:
docs/openapi.json
Location:paths→/v1/info→get→responses→200
Offending properties:{ "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InfoResponse" } } }, "name": "Service name", ← remove this "version": "Service version" ← remove this }• Fix: remove the
nameandversionkeys from the response object. The example or schema forInfoResponsealready covers those fields undercomponents/schemas/InfoResponse.• After correction, add the following validation step to CI to catch any future structural issues early:
#!/bin/bash set -euo pipefail pip install --quiet "openapi-spec-validator>=0.7.1" python - <<'PY' from openapi_spec_validator import validate_spec import json spec = json.load(open("docs/openapi.json")) validate_spec(spec) echo "✅ OpenAPI spec validation: OK" PYThen commit the fixes and re-run the validator to confirm the spec is now valid.
🧹 Nitpick comments (15)
docs/openapi.md (4)
86-97: Inconsistent status code in narrative vs. responses (500 vs. 503).The description says “returns HTTP 500” on Llama Stack connection errors, but the responses table advertises 503. Align the text with the table (or add 500 to the table if that’s the actual behavior).
Proposed doc-only fix (align to 503 as per the table):
-Handles connection errors to the -Llama Stack service by returning an HTTP 500 error. +Handles connection errors to the +Llama Stack service by returning an HTTP 503 (Service Unavailable) error.
121-135: Streaming endpoint: document transport correctly and enumerate error responses.Since the description calls out SSE, consider:
- Stating the 200 response uses text/event-stream.
- Listing 503 (and/or 500 if applicable) in the responses table.
This improves contract clarity for clients and aligns with the JSON spec changes you’re making elsewhere.
Happy to draft the rows if desired.
466-478: CORSConfiguration section: add per-field types, examples, and defaults for completeness.Right now the Type column shows “array/boolean” without element types or defaults. Suggest:
- Explicitly state “array[string]” for allow_origins/allow_methods/allow_headers.
- Document defaults (["*"] for origins/methods/headers; false for credentials).
- Mention that allow_credentials cannot be true with allow_origins ["*"] in common CORS middleware.
I can add a short example block if useful.
1014-1023: ServiceConfiguration.cors should link to the new schema.The Type cell is empty. Link it to the CORSConfiguration section for easier navigation.
Proposed edit to the table row:
-| cors | | | +| cors | [CORSConfiguration](#corsconfiguration) | |docs/openapi.json (6)
124-125: /v1/query: description says HTTP 500, responses define 503—pick one and be consistent.If the intended behavior is Service Unavailable on backend connection failures, update the description to 503. Otherwise, add a 500 response entry.
Minimal JSON patch (align to 503):
- "description": "Handle request to the /query endpoint.\n\nProcesses a POST request to the /query endpoint, forwarding the\nuser's query to a selected Llama Stack LLM or agent and\nreturning the generated response.\n\nValidates configuration and authentication, selects the appropriate model\nand provider, retrieves the LLM response, updates metrics, and optionally\nstores a transcript of the interaction. Handles connection errors to the\nLlama Stack service by returning an HTTP 500 error.\n\nReturns:\n QueryResponse: Contains the conversation ID and the LLM-generated response.", + "description": "Handle request to the /query endpoint.\n\nProcesses a POST request to the /query endpoint, forwarding the\nuser's query to a selected Llama Stack LLM or agent and\nreturning the generated response.\n\nValidates configuration and authentication, selects the appropriate model\nand provider, retrieves the LLM response, updates metrics, and optionally\nstores a transcript of the interaction. Handles connection errors to the\nLlama Stack service by returning an HTTP 503 (Service Unavailable) error.\n\nReturns:\n QueryResponse: Contains the conversation ID and the LLM-generated response.",
840-881: CORSConfiguration: add guardrails for arrays and avoid duplicates.Lint hint CKV_OPENAPI_21 suggests bounding arrays. Recommend:
- uniqueItems: true for allow_origins/methods/headers
- Optional: maxItems (e.g., 100) to satisfy tooling
Also consider documenting that ["*"] cannot be combined with allow_credentials=true in typical middleware.
Patch example for one field (apply similarly to the others):
"allow_origins": { "items": { "type": "string" }, "type": "array", + "uniqueItems": true, + "maxItems": 100, "title": "Allow Origins", "default": [ "*" ] },
1656-1659: PostgreSQLDatabaseConfiguration.port: prefer integer bounds over exclusiveMinimum 0.0.Use minimum: 1 and maximum: 65535 for clarity and interoperability with validators.
- "port": { - "type": "integer", - "exclusiveMinimum": 0.0, - "title": "Port", - "default": 5432 - }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "title": "Port", + "default": 5432 + },
2013-2018: ServiceConfiguration.port: same bounds suggestion as above.Apply minimum: 1 and maximum: 65535 instead of exclusiveMinimum 0.0.
- "port": { - "type": "integer", - "exclusiveMinimum": 0.0, - "title": "Port", - "default": 8080 - }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "title": "Port", + "default": 8080 + },
2024-2029: ServiceConfiguration.workers: enforce minimum 1 using “minimum” rather than exclusiveMinimum with float.This reads better with integer schemas and avoids tool quirks.
- "workers": { - "type": "integer", - "exclusiveMinimum": 0.0, - "title": "Workers", - "default": 1 - }, + "workers": { + "type": "integer", + "minimum": 1, + "title": "Workers", + "default": 1 + },
2044-2058: cors property: good addition—consider adding a short description.Add a one-liner so generators produce better typed clients.
"cors": { "$ref": "#/components/schemas/CORSConfiguration", + "description": "Cross-Origin Resource Sharing settings for the HTTP service.", "default": {docs/output.md (5)
86-97: /v1/query docs: mismatch between narrative (500) and table (503).Same as in openapi.md/json. Align the prose to 503 or add a 500 row if that’s the actual behavior.
-Handles connection errors to the -Llama Stack service by returning an HTTP 500 error. +Handles connection errors to the +Llama Stack service by returning an HTTP 503 (Service Unavailable) error.Also applies to: 110-115
121-135: /v1/streaming_query: call out SSE (text/event-stream) and list 503.
- Replace “...” with “text/event-stream” in the 200 row description or add a note below the table.
- Add a 503 row if backend connectivity can fail here as well.
Also applies to: 148-150
466-478: CORSConfiguration docs: specify element types and defaults.Mirror the JSON schema: array[string] for origins/methods/headers, default [""]; allow_credentials default false; and note common CORS constraint re: "" with credentials.
1003-1013: Link ServiceConfiguration.cors to CORSConfiguration.Fill in the Type column for discoverability.
-| cors | | | +| cors | [CORSConfiguration](#corsconfiguration) | |
114-114: markdownlint MD058: surround tables with blank lines.Add a blank line before and after the tables at these positions to appease the linter.
Example:
-### ✅ Responses +### ✅ Responses + | Status Code | Description | Component | ... -| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | +| 422 | Validation Error | [HTTPValidationError](#httpvalidationerror) | +Also applies to: 149-149
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (3)
docs/openapi.json(7 hunks)docs/openapi.md(7 hunks)docs/output.md(6 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
docs/output.md
114-114: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
149-149: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🪛 Checkov (3.2.334)
docs/openapi.json
[MEDIUM] 842-850: Ensure that arrays have a maximum number of items
(CKV_OPENAPI_21)
⏰ 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). (2)
- GitHub Check: build-pr
- GitHub Check: e2e_tests
🔇 Additional comments (4)
docs/openapi.md (2)
59-68: Good clarification on /v1/models behavior and failure modes.The “Raises” and “Returns” additions improve consumer expectations for this endpoint. No action needed.
178-180: Clearer “Feedback” endpoint docs—nice.The new Returns/Raises sections are helpful for integrators.
Also applies to: 191-193
docs/output.md (2)
77-79: Nice: explicit component for 200 on /v1/models.Docs now point to ModelsResponse, which helps consumers.
170-171: GET /v1/config: good—explicitly referencing Configuration.Clearer than a generic “object”.
| "description": "Handle request to the /streaming_query endpoint.\n\nThis endpoint receives a query request, authenticates the user,\nselects the appropriate model and provider, and streams\nincremental response events from the Llama Stack backend to the\nclient. Events include start, token updates, tool calls, turn\ncompletions, errors, and end-of-stream metadata. Optionally\nstores the conversation transcript if enabled in configuration.\n\nReturns:\n StreamingResponse: An HTTP streaming response yielding\n SSE-formatted events for the query lifecycle.\n\nRaises:\n HTTPException: Returns HTTP 500 if unable to connect to the\n Llama Stack server.", | ||
| "operationId": "streaming_query_endpoint_handler_v1_streaming_query_post", |
There was a problem hiding this comment.
🛠️ Refactor suggestion
/v1/streaming_query: declare SSE content type and list service errors.
- For 200, prefer text/event-stream with a string schema (as many tools expect).
- Add a 503 response mirroring /v1/query when the backend is unavailable.
Proposed minimal changes:
"responses": {
- "200": {
- "description": "Successful Response",
- "content": {
- "application/json": {
- "schema": {}
- }
- }
- },
+ "200": {
+ "description": "Successful Response",
+ "content": {
+ "text/event-stream": {
+ "schema": { "type": "string" }
+ }
+ }
+ },
+ "503": {
+ "description": "Service Unavailable",
+ "content": {
+ "application/json": {
+ "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+ }
+ }
+ },🤖 Prompt for AI Agents
In docs/openapi.json around lines 195-196, the streaming_query operation lacks
an explicit SSE response content type and is missing a service-unavailable
response; update the 200 response to use content type "text/event-stream" with a
simple string schema (since SSE is a text stream of events) and add a 503
response object mirroring the /v1/query 503 (service unavailable when backend is
down) with the same description and error schema used there so consumers can
detect backend unavailability.
1 participant
Description
LCORE-535: Regenerated OpenAPI schema
Type of change
Related Tickets & Documents
Summary by CodeRabbit
New Features
Documentation