LCORE-632: Regenerated OpenAPI specification #590
Conversation
WalkthroughAdds new public schemas and fields to OpenAPI documentation: extends QueryResponse with rag_chunks, tool_calls, referenced_documents; introduces RAGChunk, ToolCall, ReferencedDocument; adds ConversationCacheConfiguration and InMemoryCacheConfig; updates Configuration to include conversation_cache; refreshes examples and markdown sections accordingly. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Client
participant API
participant RAG as RAG Retriever
participant Tools as Tool Runner
Client->>API: POST /query (prompt)
API->>RAG: Retrieve chunks
RAG-->>API: RAGChunk[]
alt tools required
API->>Tools: Invoke tool(s) with arguments
Tools-->>API: ToolCall results
end
API-->>Client: QueryResponse { rag_chunks, tool_calls?, referenced_documents }
note over API,Client: Response schema updated in OpenAPI
sequenceDiagram
autonumber
actor Admin
participant Service as Service Config
Admin->>Service: Set conversation_cache config
Service-->>Admin: Confirms type (noop/memory/sqlite/postgres) and params (e.g., InMemoryCacheConfig.max_entries)
note over Service: New ConversationCacheConfiguration in OpenAPI
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ 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. 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
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)
676-679: Inconsistent field name in example vs schemaThe 200 DELETE example uses "message" but schema defines "response". Align the example field name.
- "success": true, - "message": "Conversation deleted successfully" + "success": true, + "response": "Conversation deleted successfully"
🧹 Nitpick comments (19)
docs/output.md (7)
565-566: Document the new field with a link and brief descriptionAdd a short description and link to ConversationCacheConfiguration to make this discoverable.
-| conversation_cache | | | +| conversation_cache | | Conversation cache settings (see ConversationCacheConfiguration) |
568-579: Clarify allowed values and which sub-config appliesState allowed type values (noop, memory, sqlite, postgres) and that only the matching sub-config should be set.
-Conversation cache configuration. +Conversation cache configuration. + +Allowed types: noop, memory, sqlite, postgres. +Only the sub-configuration matching the selected type should be populated (e.g., memory when type=memory).
1131-1139: Remove TODOs from public API docsThe TODO lines leak internal roadmap into public docs. Either document them formally or omit for now.
- TODO: truncated: Whether conversation history was truncated. - TODO: input_tokens: Number of tokens sent to LLM. - TODO: output_tokens: Number of tokens received from LLM. - TODO: available_quotas: Quota available as measured by all configured quota limiters - TODO: tool_results: List of tool results.
1141-1148: Specify type for tool_callsThe type column is empty; specify array or null to match the schema.
-| tool_calls | | List of tool calls made during response generation | +| tool_calls | array or null | List of tool calls made during response generation |
1156-1161: Add types for RAGChunk fieldsDocument types for source and score to match the schema (string or null, number or null).
-| source | | Source document or URL | -| score | | Relevance score | +| source | string or null | Source document or URL | +| score | number or null | Relevance score |
1196-1210: Make doc_url type explicit and fix capitalizationUse “URL” and specify the type and format.
- doc_url: Url to the referenced doc. + doc_url: URL to the referenced document. ... -| doc_url | | URL of the referenced document | +| doc_url | string (URI) or null | URL of the referenced document |
1278-1289: Specify type for ToolCall.resultAdd “object or null” to align with the schema.
-| result | | Result from the tool | +| result | object or null | Result from the tool |docs/openapi.json (5)
1181-1234: Enforce config consistency with oneOf/if-thenCurrently any combination of sub-configs is allowed. Add a discriminated union tying type to the required sub-config to prevent misconfiguration.
"ConversationCacheConfiguration": { - "properties": { + "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "noop", "memory", "sqlite", "postgres" ] }, { "type": "null" } ], "title": "Type" }, "memory": { "anyOf": [ { "$ref": "#/components/schemas/InMemoryCacheConfig" }, { "type": "null" } ] }, "sqlite": { "anyOf": [ { "$ref": "#/components/schemas/SQLiteDatabaseConfiguration" }, { "type": "null" } ] }, "postgres": { "anyOf": [ { "$ref": "#/components/schemas/PostgreSQLDatabaseConfiguration" }, { "type": "null" } ] } }, + "oneOf": [ + { "properties": { "type": { "const": "noop" } }, "required": ["type"] }, + { "properties": { "type": { "const": "memory" }, "memory": {} }, "required": ["type","memory"] }, + { "properties": { "type": { "const": "sqlite" }, "sqlite": {} }, "required": ["type","sqlite"] }, + { "properties": { "type": { "const": "postgres" }, "postgres": {} }, "required": ["type","postgres"] } + ], "additionalProperties": false, "type": "object", "title": "ConversationCacheConfiguration", "description": "Conversation cache configuration." },
1819-1833: Prefer minimum: 1 over exclusiveMinimum: 0 for compatibilitySome tools mishandle exclusiveMinimum on integers. Using minimum: 1 is clearer and widely supported.
- "max_entries": { - "type": "integer", - "exclusiveMinimum": 0.0, - "title": "Max Entries" - } + "max_entries": { + "type": "integer", + "minimum": 1, + "title": "Max Entries" + }
2455-2494: Optional: add default empty arrays for consistencyConsider default: [] for referenced_documents to mirror rag_chunks, easing client handling.
"referenced_documents": { "items": { "$ref": "#/components/schemas/ReferencedDocument" }, "type": "array", "title": "Referenced Documents", - "description": "List of documents referenced in generating the response", + "description": "List of documents referenced in generating the response", + "default": [],
2501-2502: Remove TODOs from public descriptionKeep schema descriptions clean; track TODOs elsewhere.
- "description": "Model representing LLM response to a query.\n\nAttributes:\n conversation_id: The optional conversation ID (UUID).\n response: The response.\n rag_chunks: List of RAG chunks used to generate the response.\n referenced_documents: The URLs and titles for the documents used to generate the response.\n tool_calls: List of tool calls made during response generation.\n TODO: truncated: Whether conversation history was truncated.\n TODO: input_tokens: Number of tokens sent to LLM.\n TODO: output_tokens: Number of tokens received from LLM.\n TODO: available_quotas: Quota available as measured by all configured quota limiters\n TODO: tool_results: List of tool results.", + "description": "Model representing LLM response to a query.\n\nAttributes:\n conversation_id: The optional conversation ID (UUID).\n response: The response.\n rag_chunks: List of RAG chunks used to generate the response.\n referenced_documents: The URLs and titles for the documents used to generate the response.\n tool_calls: List of tool calls made during response generation.",
2617-2645: Make doc_url required and non-null (or justify nullability)For traceability, doc_url should typically be required and a URI. If nullability is intentional (e.g., offline sources), document that in markdown.
- "doc_url": { - "anyOf": [ - { - "type": "string", - "minLength": 1, - "format": "uri" - }, - { - "type": "null" - } - ], - "title": "Doc Url", - "description": "URL of the referenced document" - }, + "doc_url": { + "type": "string", + "minLength": 1, + "format": "uri", + "title": "Doc Url", + "description": "URL of the referenced document" + }, ... - "required": [ - "doc_title" - ], + "required": [ + "doc_url", + "doc_title" + ],docs/openapi.md (7)
565-566: Document the new field with a link and brief descriptionMirror the JSON schema by referencing ConversationCacheConfiguration.
-| conversation_cache | | | +| conversation_cache | | Conversation cache settings (see ConversationCacheConfiguration) |
568-579: Clarify allowed values and sub-config selectionAdd allowed type values and note only matching sub-config should be set.
-Conversation cache configuration. +Conversation cache configuration. + +Allowed types: noop, memory, sqlite, postgres. +Only the sub-configuration matching the selected type should be populated.
1129-1139: Remove TODOs from public docsSame rationale as JSON schema: keep public docs clean.
- TODO: truncated: Whether conversation history was truncated. - TODO: input_tokens: Number of tokens sent to LLM. - TODO: output_tokens: Number of tokens received from LLM. - TODO: available_quotas: Quota available as measured by all configured quota limiters - TODO: tool_results: List of tool results.
1141-1148: Specify type for tool_callsFill in the type to match the schema.
-| tool_calls | | List of tool calls made during response generation | +| tool_calls | array or null | List of tool calls made during response generation |
1156-1161: Add types for RAGChunk fieldsMatch the schema types.
-| source | | Source document or URL | -| score | | Relevance score | +| source | string or null | Source document or URL | +| score | number or null | Relevance score |
1196-1210: Make doc_url type explicit and fix capitalizationClarify “URL” and type.
- doc_url: Url to the referenced doc. + doc_url: URL to the referenced document. ... -| doc_url | | URL of the referenced document | +| doc_url | string (URI) or null | URL of the referenced document |
1278-1289: Specify type for ToolCall.resultAdd “object or null”.
-| result | | Result from the tool | +| result | object or null | Result from the tool |
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/openapi.json(7 hunks)docs/openapi.md(5 hunks)docs/output.md(5 hunks)
⏰ 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 (1)
docs/openapi.json (1)
1165-1167: LGTM: configuration now exposes conversation_cacheNew field correctly references ConversationCacheConfiguration and remains optional.
| "conversation_id": "123e4567-e89b-12d3-a456-426614174000", | ||
| "response": "LLM answer" | ||
| "response": "LLM answer", | ||
| "referenced_documents": [ | ||
| { | ||
| "doc_url": "https://docs.openshift.com/container-platform/4.15/operators/olm/index.html", | ||
| "doc_title": "Operator Lifecycle Manager (OLM)" | ||
| } | ||
| ] | ||
| }, |
There was a problem hiding this comment.
Invalid placement of example fields in response
The example fields are placed directly under 200, not under content.application/json.example. Move them to “example” within the media type.
"200": {
"description": "Successful Response",
"content": {
"application/json": {
- "schema": {
- "$ref": "#/components/schemas/QueryResponse"
- }
+ "schema": {
+ "$ref": "#/components/schemas/QueryResponse"
+ },
+ "example": {
+ "conversation_id": "123e4567-e89b-12d3-a456-426614174000",
+ "response": "LLM answer",
+ "referenced_documents": [
+ {
+ "doc_url": "https://docs.openshift.com/container-platform/4.15/operators/olm/index.html",
+ "doc_title": "Operator Lifecycle Manager (OLM)"
+ }
+ ]
+ }
}
},
- "conversation_id": "123e4567-e89b-12d3-a456-426614174000",
- "response": "LLM answer",
- "referenced_documents": [
- {
- "doc_url": "https://docs.openshift.com/container-platform/4.15/operators/olm/index.html",
- "doc_title": "Operator Lifecycle Manager (OLM)"
- }
- ]
}📝 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.
| "conversation_id": "123e4567-e89b-12d3-a456-426614174000", | |
| "response": "LLM answer" | |
| "response": "LLM answer", | |
| "referenced_documents": [ | |
| { | |
| "doc_url": "https://docs.openshift.com/container-platform/4.15/operators/olm/index.html", | |
| "doc_title": "Operator Lifecycle Manager (OLM)" | |
| } | |
| ] | |
| }, | |
| "200": { | |
| "description": "Successful Response", | |
| "content": { | |
| "application/json": { | |
| "schema": { | |
| "$ref": "#/components/schemas/QueryResponse" | |
| }, | |
| "example": { | |
| "conversation_id": "123e4567-e89b-12d3-a456-426614174000", | |
| "response": "LLM answer", | |
| "referenced_documents": [ | |
| { | |
| "doc_url": "https://docs.openshift.com/container-platform/4.15/operators/olm/index.html", | |
| "doc_title": "Operator Lifecycle Manager (OLM)" | |
| } | |
| ] | |
| } | |
| } | |
| } | |
| } |
🤖 Prompt for AI Agents
In docs/openapi.json around lines 154 to 162, the response example JSON is
incorrectly placed directly under the HTTP 200 response object; move that
example into the media type path: add a content -> "application/json" -> example
(or examples) property and place the existing example object there, removing it
from the top-level 200 object so the OpenAPI response follows the structure: 200
-> description -> content -> "application/json" -> example.
1 participant
Description
Regenerated OpenAPI specification
Type of change
Related Tickets & Documents
Summary by CodeRabbit
New Features
Documentation