Skip to content

LCORE-1348: Regenerated OpenAPI doc #1486

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tisnik merged 1 commit into from
Apr 12, 2026
+68 −3
Merged

LCORE-1348: Regenerated OpenAPI doc #1486

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 49 additions & 1 deletion docs/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4770,6 +4770,26 @@
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
},
"examples": {
"model": {
"value": {
"detail": {
"cause": "Model with ID gpt-4-turbo is not configured",
"response": "Model not found"
}
}
}
}
}
}
},
Comment on lines +4773 to +4792
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Use a 5xx here instead of 404.

RlsapiV1InferRequest has no model or provider field, so "model not configured" on /v1/infer can only come from server configuration/backend state, not from a client-addressable missing resource. Documenting it as 404 will send clients down the wrong error-handling path; keep this under the existing 5xx responses unless the endpoint starts accepting explicit model IDs.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/openapi.json` around lines 4773 - 4792, The OpenAPI response for the
/v1/infer path currently uses a 404 (NotFoundResponse) with an example about
"Model not configured", but RlsapiV1InferRequest has no model/provider field so
this is a server-side configuration/backend error; change the status code from
404 to an appropriate 5xx (e.g., 500 or 503), update the response description to
reflect a server configuration/backend error, and point the schema reference to
the existing 5xx error schema (instead of NotFoundResponse); also update the
example payload key/value to match that 5xx schema so clients will treat it as a
server error rather than a missing-client resource.

"413": {
"description": "Prompt is too long",
"content": {
Expand Down Expand Up @@ -9157,7 +9177,35 @@
"title": "Call Id"
},
"output": {
"type": "string",
"anyOf": [
{
"type": "string"
},
{
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/OpenAIResponseInputMessageContentText"
},
{
"$ref": "#/components/schemas/OpenAIResponseInputMessageContentImage"
},
{
"$ref": "#/components/schemas/OpenAIResponseInputMessageContentFile"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"input_file": "#/components/schemas/OpenAIResponseInputMessageContentFile",
"input_image": "#/components/schemas/OpenAIResponseInputMessageContentImage",
"input_text": "#/components/schemas/OpenAIResponseInputMessageContentText"
}
}
},
"type": "array"
}
],
Comment on lines +9180 to +9208
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Expected: each mapped schema should require `type` if it is used behind a discriminator.
python - <<'PY'
import json
from pathlib import Path

spec = json.loads(Path("docs/openapi.json").read_text())
schemas = spec["components"]["schemas"]

for name in [
    "OpenAIResponseInputMessageContentText",
    "OpenAIResponseInputMessageContentImage",
    "OpenAIResponseInputMessageContentFile",
]:
    schema = schemas[name]
    print(f"\n## {name}")
    print("required =", schema.get("required"))
    print("additionalProperties =", schema.get("additionalProperties", "<unspecified>"))
    print("type.const =", schema.get("properties", {}).get("type", {}).get("const"))
PY

Repository: lightspeed-core/lightspeed-stack

Length of output: 438

The discriminator-based oneOf is unreliable because type is not required on any mapped schema.

The new output array branch uses a discriminator on type but references OpenAIResponseInputMessageContentText, OpenAIResponseInputMessageContentImage, and OpenAIResponseInputMessageContentFile—none of which list type in their required fields. While all three define type as a constant, the constant constraint does not enforce presence. Without requiring type, clients and validators cannot reliably distinguish between branches; a payload lacking type could ambiguously match multiple schemas.

Add "type" to the required array in each of these three schemas. Optionally, set "additionalProperties": false on Image and File to prevent unexpected fields.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/openapi.json` around lines 9180 - 9208, The discriminator on the output
array is unsafe because the mapped schemas
OpenAIResponseInputMessageContentText, OpenAIResponseInputMessageContentImage,
and OpenAIResponseInputMessageContentFile do not require the "type" property;
update each of those three schema definitions to include "type" in their
"required" array so validators and clients can reliably discriminate, and
(optional but recommended) add "additionalProperties": false to
OpenAIResponseInputMessageContentImage and OpenAIResponseInputMessageContentFile
to prevent unexpected fields.

"title": "Output"
},
"type": {
Expand Down
21 changes: 19 additions & 2 deletions docs/openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,7 @@ Returns:
HTMLResponse: The HTML content of the index page, including a heading,
embedded image with the service icon, and links to the API documentation
via Swagger UI and ReDoc.
Handle GET requests to the root ("/") endpoint and returns the static HTML index page.
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Remove duplicated root-endpoint description.

Line 69 repeats the exact sentence already documented earlier for the same section, which adds noise to generated docs.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/openapi.md` at line 69, Remove the duplicated sentence "Handle GET
requests to the root (\"/\") endpoint and returns the static HTML index page."
in the docs/openapi.md file (the repeated root-endpoint description) so only the
original occurrence remains; search for the exact sentence text and delete the
redundant copy to avoid duplicate documentation entries.




Expand Down Expand Up @@ -4463,6 +4464,7 @@ Global service configuration.
| a2a_state | | Configuration for A2A protocol persistent state storage. |
| quota_handlers | | Quota handlers configuration |
| azure_entra_id | | |
| rlsapi_v1 | | Configuration for the rlsapi v1 /infer endpoint used by the RHEL Lightspeed Command Line Assistant (CLA). |
| splunk | | Splunk HEC configuration for sending telemetry events. |
| deployment_environment | string | Deployment environment name (e.g., 'development', 'staging', 'production'). Used in telemetry events. |
| rag | | Configuration for all RAG strategies (inline and tool-based). |
Expand Down Expand Up @@ -4727,7 +4729,6 @@ Service customization.
| agent_card_path | | |
| agent_card_config | | |
| custom_profile | | |
| allow_verbose_infer | boolean | |


## DatabaseConfiguration
Expand Down Expand Up @@ -5467,7 +5468,7 @@ This represents the output of a function call that gets passed back to the model
| Field | Type | Description |
|-------|------|-------------|
| call_id | string | |
| output | string | |
| output | | |
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Restore explicit type information for OpenAIResponseInputFunctionToolCallOutput.output.

Line 5471 now shows an empty type, which hides the contract for clients. Please document the union explicitly (string or structured content array) instead of leaving it blank.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/openapi.md` at line 5471, Restore the explicit union type for
OpenAIResponseInputFunctionToolCallOutput.output instead of leaving it blank:
update the OpenAPI docs so OpenAIResponseInputFunctionToolCallOutput.output is
documented as "string | StructuredContentItem[]" (or the project's existing
structured-content item type name, e.g., OpenAIResponseStructuredContentItem[]),
describing it accepts either a plain string or an array of structured content
items; ensure the union and the referenced structured item schema are linked so
clients can see the contract.

| type | string | |
| id | | |
| status | | |
Expand Down Expand Up @@ -6661,6 +6662,22 @@ Attributes:
| version | string | Command line assistant version |


## RlsapiV1Configuration


Configuration for the rlsapi v1 /infer endpoint.

Settings specific to the RHEL Lightspeed Command Line Assistant (CLA)
stateless inference endpoint. Kept separate from shared configuration
sections so that CLA-specific options do not affect other endpoints.


| Field | Type | Description |
|-------|------|-------------|
| allow_verbose_infer | boolean | Allow /v1/infer to return extended metadata (tool_calls, rag_chunks, token_usage) when the client sends "include_metadata": true. Should NOT be enabled in production. If production use is needed, consider RBAC-based access control via an Action.RLSAPI_V1_INFER authorization rule. |
| quota_subject | | Identity field used as the quota subject for /v1/infer. When set, token quota enforcement is enabled for this endpoint. Requires quota_handlers to be configured. "org_id" and "system_id" require rh-identity authentication; falls back to user_id when rh-identity data is unavailable. |
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Fix quota_subject behavior description to match implementation.

Line 6678 states it “falls back to user_id when rh-identity data is unavailable,” but the implementation validates quota_subject against auth mode and can fail fast when required identity data is missing to prevent quota bypass. This doc text is misleading for operators configuring enforcement.

Based on learnings and provided snippets: src/models/config.py:2018-2060 and src/app/endpoints/rlsapi_v1.py:491-526 show strict validation/fail-fast behavior rather than a permissive fallback.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/openapi.md` at line 6678, Update the OpenAPI docs entry for
quota_subject to reflect the implementation's strict validation rather than a
permissive fallback: state that quota_subject is validated against the current
auth mode and that missing required RH-Identity data will cause validation to
fail (preventing quota enforcement setup) instead of silently falling back to
user_id; reference the enforcement/validation logic in the Config handling of
quota_subject and the /v1/infer request auth checks in the RLS API handler so
operators know the setting may be rejected when RH-Identity info is absent.



## RlsapiV1Context


Expand Down
Loading