LCORE-973: updated generated doc#865
Conversation
WalkthroughDocumentation and schema enrichment across configuration and OpenAPI files. Changes add descriptive titles and expanded field descriptions to JSON schema definitions, update HTML styling and remove legacy IE8 shiv, refine PlantUML diagram types from Optional to required, and expand Markdown documentation with clarifying notes. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes
Possibly related PRs
Suggested reviewers
Pre-merge checks and finishing touches❌ Failed checks (1 inconclusive)
✅ Passed checks (2 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 |
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/openapi.json (3)
4285-4288: Content-type/schema mismatch for text outputsFor text/plain and text/html responses you reference JSON object schemas (UnauthorizedResponse/ForbiddenResponse/InternalServerErrorResponse). Code generators and validators expect a string schema for these media types.
Proposed fix:
- Use type "string" for text/plain and text/html variants.
- Keep object schemas only under application/json.
Example diffs:
/metrics 401 text/plain:
- "text/plain": { - "schema": { - "$ref": "#/components/schemas/UnauthorizedResponse" - } - } + "text/plain": { + "schema": { "type": "string" } + }Repeat similarly for 403, 500, 503 under /metrics, and for root GET 401 text/html.
Also applies to: 4307-4310, 4329-4332, 4351-4354, 67-71
2607-2613: ConversationDeleteResponse example contradicts success flag“not found” example sets success: true with a failure message. Should be false and message spelling should be “cannot”.
Suggested diffs:
/v1/conversations/{conversation_id} DELETE examples:
- "response": "Conversation can not be deleted", - "success": true + "response": "Conversation cannot be deleted", + "success": falseSchema examples (components):
- "response": "Conversation can not be deleted", - "success": true + "response": "Conversation cannot be deleted", + "success": falseAlso applies to: 4982-4988
1377-1379: Typo: “attatchment” → “attachment”Fix spelling in 422 examples across endpoints and components.
Example diff:
- "cause": "Invalid attatchment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']", + "cause": "Invalid attachment type: must be one of ['text/plain', 'application/json', 'application/yaml', 'application/xml']",Also applies to: 1657-1659, 3596-3598, 3879-3881, 7680-7682
🧹 Nitpick comments (14)
docs/openapi.json (8)
5920-5921: JsonPathOperator: enum descriptionGood clarification that it’s an enum. Consider aligning “JSONPath” spelling consistently across file (see related comment below).
1031-1033: Consistent capitalization: RAG vs RagUse “RAG” consistently in summaries and example messages.
Example diffs:
- "summary": "Get Rag Endpoint Handler", + "summary": "Get RAG Endpoint Handler"- "cause": "Rag with ID ... does not exist", + "cause": "RAG with ID ... does not exist",Also applies to: 6200-6202
4495-4496: Title capitalization: K8S/K8s and API/CAUse standard capitalization: “K8s Cluster API”, “K8s CA Cert Path”.
- "title": "K8S Cluster Api" + "title": "K8s Cluster API" - "title": "K8S Ca Cert Path" + "title": "K8s CA Cert Path"Also applies to: 4507-4508
5978-5984: JSONPath naming consistencyUse “JSONPath” consistently (not “JSON path”).
- "title": "JSON path", - "description": "JSONPath expression to evaluate against the JWT payload" + "title": "JSONPath", + "description": "JSONPath expression to evaluate against the JWT payload"Also consider aligning “JSON path comparison operator” to “JSONPath comparison operator”.
6253-6263: PostgreSQL: gss_encmode title clarity“GSS encmode” is awkward; suggest “GSS encryption mode” (or “gssencmode” to mirror libpq).
- "title": "GSS encmode", + "title": "GSS encryption mode",
6248-6251: PostgreSQL: “Name space” → “Namespace”- "title": "Name space", + "title": "Namespace",
6296-6304: Provider health status example casingExamples use “OK” while ProviderHealthStatus status examples use “ok”. Consider standardizing to a single casing across docs (prefer lower-case “ok”).
Also applies to: 6416-6422
3736-3743: Streaming v2: narrow 200 content typesSSE responses are better advertised only under text/event-stream. The application/json entry with a string payload can confuse clients. Consider removing application/json here and keeping text/event-stream with a string schema + example.
docs/config.html (3)
327-471: Configuration & CORS sections are much clearer; consider tiny grammar tweaksThe added
colgroups and expanded descriptions for CORS and the mainConfigurationfields are a solid improvement and consistent with the JSON schema.Minor optional nits you may want to address:
- Line 408–409: “user data(transcription history and feedbacks)” → consider “user data (transcription history and feedback)” (space after “data” and “feedback” is usually uncountable).
- Line 450–452: “One LLM provider and one its model might be selected as default ones.” → consider “One LLM provider and one of its models can be selected as defaults.”
These are purely wording polish; structure and semantics look fine.
472-509: Conversation history, custom profiles, inference & JsonPath docs are consistent; small wording nitThe new descriptions for
ConversationHistoryConfiguration,CustomProfile,InferenceConfiguration, and the JSONPath operator note accurately reflect the schemas and make the configuration semantics easier to understand.Optional wording suggestion:
- Line 531–532: “Dictionary containing map of system prompts” → “Dictionary mapping system prompt names to prompts” or simply “Map of system prompts”.
Otherwise this group of sections looks good.
Also applies to: 523-532, 622-646, 651-652
1238-1273: UserDataCollection docs are clearer; consider calling out data retention/PIIThe descriptions for
feedback_enabled,feedback_storage,transcripts_enabled, andtranscripts_storagenow clearly describe what gets persisted and where.Given these options control storage of potentially sensitive user data and transcripts, you might optionally add a brief note pointing readers to any existing privacy/retention controls or policies (e.g., recommended storage locations, rotation/retention guidance).
docs/config.json (2)
814-858: Clarifyquota_increaseoptionality vs required status in QuotaLimiterConfigurationThe description states that
quota_increase“is the value (if specified) used to increase the quota when the period is reached” and distinguishes use cases where you either reset the quota viainitial_quotaor increase it viaquota_increase. However, in the schemaquota_increaseis listed in therequiredarray.To avoid confusing config authors, consider either:
- Making
quota_increasetruly optional in the schema (remove it fromrequired), or- Adjusting the prose to drop “if specified” and explicitly say that both
initial_quotaandquota_increasemust be provided, with guidance on how to set one to0if unused.Same applies to the “two basic use cases” description, which currently implies that you can omit one of the fields entirely.
875-885: Clarify semantics of nullablerequired_entitlements
RHIdentityConfiguration.required_entitlementsis typed as an array,nullable: true,default: null, but the description says “List of all required entitlements.”If
nullis a meaningful “no entitlements required” state distinct from an empty list, consider briefly documenting that distinction (e.g.,nullvs[]). If there is no intended difference, making it non-nullable or defaulting to[]could simplify the contract.docs/config.puml (1)
24-31: Consider restoring primitive types for some scalar fields in the UMLSeveral important scalar fields are now shown without explicit types in the diagram even though their JSON schemas and surrounding docs define them as primitives, for example:
ByokRag.db_path,ByokRag.embedding_dimensionInMemoryCacheConfig.max_entriesJwkConfiguration.url,JwkConfiguration.jwt_configurationPostgreSQLDatabaseConfiguration.password,PostgreSQLDatabaseConfiguration.portQuotaLimiterConfiguration.initial_quota,QuotaLimiterConfiguration.quota_increaseQuotaSchedulerConfiguration.periodFor readers using this diagram as a quick reference, having at least the base type (
str/int/bool/ referenced config type) would be helpful. If the omission is due to strippingAnnotated[...]or URL/path types, consider mapping those to their underlying primitives when rendering the UML.Also applies to: 85-87, 96-104, 128-138, 147-156
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
docs/config.pngis excluded by!**/*.pngdocs/config.svgis excluded by!**/*.svg
📒 Files selected for processing (7)
docs/config.html(15 hunks)docs/config.json(14 hunks)docs/config.md(7 hunks)docs/config.puml(6 hunks)docs/openapi.json(18 hunks)docs/openapi.md(9 hunks)docs/output.md(9 hunks)
🧰 Additional context used
🧠 Learnings (3)
📚 Learning: 2025-11-24T16:58:04.410Z
Learnt from: CR
Repo: lightspeed-core/lightspeed-stack PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T16:58:04.410Z
Learning: Applies to src/models/config.py : All configuration must use Pydantic models extending `ConfigurationBase` with `extra="forbid"` to reject unknown fields
Applied to files:
docs/config.puml
📚 Learning: 2025-11-24T16:58:04.410Z
Learnt from: CR
Repo: lightspeed-core/lightspeed-stack PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T16:58:04.410Z
Learning: Applies to src/models/**/*.py : Pydantic configuration classes must extend `ConfigurationBase`; data models must extend `BaseModel`
Applied to files:
docs/config.puml
📚 Learning: 2025-11-24T16:58:04.410Z
Learnt from: CR
Repo: lightspeed-core/lightspeed-stack PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-11-24T16:58:04.410Z
Learning: Applies to src/models/config.py : Use type hints `Optional[FilePath]`, `PositiveInt`, `SecretStr` for Pydantic configuration models
Applied to files:
docs/config.puml
🪛 markdownlint-cli2 (0.18.1)
docs/config.md
218-218: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
219-219: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
243-243: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
244-244: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
245-245: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
docs/output.md
4453-4453: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4454-4454: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4478-4478: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4479-4479: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4480-4480: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
docs/openapi.md
4453-4453: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4454-4454: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4478-4478: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4479-4479: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
4480-4480: Unordered list indentation
Expected: 0; Actual: 2
(MD007, ul-indent)
⏰ 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: Konflux kflux-prd-rh02 / lightspeed-stack-on-pull-request
- GitHub Check: build-pr
- GitHub Check: e2e_tests (azure)
- GitHub Check: e2e_tests (ci)
🔇 Additional comments (27)
docs/openapi.md (2)
3871-5051: Documentation enhancements are clear and well-structured.The additions throughout the Components section effectively clarify field purposes and types. The new descriptions for AccessRule, ByokRag, ConversationHistoryConfiguration, CustomProfile, InferenceConfiguration, JwkConfiguration, JwtConfiguration, and UserDataCollection provide helpful context for API consumers. The "Note: not a real model" clarifications for enumerations (Action, JsonPathOperator) are particularly useful.
4453-4454: Fix markdown list indentation to comply with linting standards.The unordered lists under "Useful resources:" sections in JwkConfiguration (lines 4453-4454) and JwtConfiguration (lines 4478-4480) use 2-space indentation instead of the required 0-space indentation. This violates the MD007 markdown linting rule.
Apply the following fix:
JWK (JSON Web Key) configuration. A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. Useful resources: - - [JSON Web Key](https://openid.net/specs/draft-jones-json-web-key-03.html) - - [RFC 7517](https://www.rfc-editor.org/rfc/rfc7517) + - [JSON Web Key](https://openid.net/specs/draft-jones-json-web-key-03.html) + - [RFC 7517](https://www.rfc-editor.org/rfc/rfc7517)Apply the same fix to JwtConfiguration.
docs/config.md (2)
10-72: Configuration documentation is accurate and improves clarity for users.Field descriptions in AccessRule, AuthorizationConfiguration, ByokRag, and other sections now provide meaningful context. The addition of the "Note: not a real model" annotation for Action and JsonPathOperator enumerations helps distinguish enumerations from actual data models. Documentation is consistent with openapi.md updates.
218-219: Fix markdown list indentation to comply with linting standards.The unordered lists under "Useful resources:" sections in JwkConfiguration and JwtConfiguration use 2-space indentation instead of the required 0-space indentation. This violates the MD007 markdown linting rule.
Apply the following fix:
JWK (JSON Web Key) configuration. A JSON Web Key (JWK) is a JavaScript Object Notation (JSON) data structure that represents a cryptographic key. Useful resources: - - [JSON Web Key](https://openid.net/specs/draft-jones-json-web-key-03.html) - - [RFC 7517](https://www.rfc-editor.org/rfc/rfc7517) + - [JSON Web Key](https://openid.net/specs/draft-jones-json-web-key-03.html) + - [RFC 7517](https://www.rfc-editor.org/rfc/rfc7517)Apply the same fix to JwtConfiguration (lines 243-245).
docs/output.md (2)
1-5051: Documentation consistency across all three files is well-maintained.The output documentation mirrors the improvements made in openapi.md and config.md, providing consistent descriptions and clarifications across the generated documentation surface. Field descriptions are clear, enumeration notes are helpful, and JWT/JWK configuration guidance is appropriately expanded.
4453-4454: Fix markdown list indentation to comply with linting standards.Same markdown indentation issues as in docs/openapi.md. The unordered lists under "Useful resources:" sections in JwkConfiguration (lines 4453-4454) and JwtConfiguration (lines 4478-4480) use 2-space indentation instead of 0-space indentation, violating MD007.
Apply consistent fixes across all affected sections.
Also applies to: 4478-4480
docs/openapi.json (11)
4367-4377: AccessRule: titles/descriptions look goodClearer naming for role and allowed actions. No issues.
4416-4417: Action enum: description addition LGTMHelpful note that this is an enum, not a model.
4542-4544: AuthorizationConfiguration: clarity improvements“Access rules” title/description are clearer. Good change.
4629-4663: ByokRag: improved field docsTitles/descriptions for IDs, types, dimensions, and paths read well. No schema impact detected.
Also applies to: 4673-4674
5118-5156: ConversationHistoryConfiguration: consistent labelingType and backend section titles/descriptions are clearer; nullability preserved. Looks good.
5355-5365: CustomProfile: clearer labels“Path to custom profile” and “System prompts” titles are improvements. Good.
5780-5793: InferenceConfiguration: defaults documentedTitles/descriptions for default model/provider are clearer. No issues.
5929-5935: JwkConfiguration/JwtConfiguration cross‑linksStrong improvements explaining JWK/JWT and linking related schema. No issues.
Also applies to: 5943-5944
5950-5966: JwtConfiguration: claim/rules documentationHelpful descriptions; no schema changes. LGTM.
Also applies to: 5971-5972
7192-7193: RHIdentityConfiguration: entitlement list clarityGood clarification. LGTM.
7692-7693: UserDataCollection: clearer titles/descriptionsImproved clarity for feedback/transcripts toggles and storage paths. LGTM.
Also applies to: 7705-7706, 7710-7711, 7723-7724
docs/config.html (4)
63-66: Responsive SVG styling looks goodMaking SVGs auto-height with max-width 100% aligns them with existing image handling and improves layout on narrow screens. No issues spotted.
177-205: RBAC “Configuration schema” intro and Action note are clearThe new top-level “📋 Configuration schema” heading and the clarifications for
AccessRuleandAction(explicitly callingActionan enumeration, not a real model) read well and match the JSON schema updates.
654-707: JWT/JWK documentation is a strong upgradeThe expanded explanations for JWK and JWT, plus the resource links and clarified field descriptions (
url,user_id_claim,username_claim,role_rules), align with common JWT/JWK terminology and with the JSON schema changes. This should make auth configuration much less opaque for readers.
879-956: PostgreSQL and quota limiter docs are detailed and consistentThe new PostgreSQL configuration explanation (including references and field-level descriptions) and the expanded quota limiter/scheduler narrative clearly describe how these settings work. The table fields match the JSON schema (host/port/db/user/password/namespace/ssl_mode/gss_encmode/ca_cert_path, limiter periods and quotas).
No semantic issues spotted here.
Also applies to: 957-1067
docs/config.json (4)
13-35: RBAC and BYOK schema descriptions are consistent and helpfulThe added descriptions/titles for:
AccessRule.role/AccessRule.actions- the
Actionenum (explicitly called out as an enumeration, not a real model)AuthorizationConfiguration.access_rules- the
ByokRagfields (rag_id,rag_type,embedding_model,embedding_dimension,vector_db_id,db_path)are clear and match the intent of the configuration. They also line up with the HTML documentation.
Also applies to: 116-135, 132-183
331-384: Conversation history, cache, custom profile, inference, and JWT config enrichments look correctThe new
description/titleentries for:
ConversationHistoryConfiguration.type,memory,sqlite,postgresCustomProfile.pathandCustomProfile.promptsInferenceConfiguration.default_modelanddefault_providerJwtConfiguration.user_id_claim,username_claim, androle_rulesaccurately describe the semantics and are consistent with the surrounding docs and the HTML tables. This is a good improvement in discoverability.
Also applies to: 485-523, 502-523, 559-585
535-557: JWK/JWT, MCP, Llama Stack, Service, and TLS schema docs are solidThe expanded descriptions and resource links for:
JwkConfiguration(JWK overview,url,jwt_configuration)JwtConfigurationModelContextProtocolServerLlamaStackConfigurationServiceConfigurationTLSConfigurationare technically accurate and align well with how these pieces are used in configuration. No inconsistencies with the UML or HTML documentation stood out.
Also applies to: 558-585, 628-663, 664-691, 906-961, 962-990
991-1024: UserDataCollection schema docs are clearThe new titles and descriptions for
feedback_enabled,feedback_storage,transcripts_enabled, andtranscripts_storageaccurately convey behavior and match the HTML documentation. This should help integrators understand the implications of toggling these flags.docs/config.puml (2)
21-31: RBAC, BYOK, and CORS diagram updates align with schemas
AuthorizationConfiguration.access_rules : list[AccessRule]now matches its array nature.ByokRagfields (rag_id,rag_type,embedding_model,embedding_dimension,vector_db_id,db_path) andCORSConfiguration(allow_credentials,allow_headers,allow_methods,allow_origins)are all represented consistently with the JSON schema and HTML docs. This keeps the UML in sync with the public configuration surface.
Also applies to: 32-38
39-54: New config relationships and QuotaSchedulerConfiguration class look correctThe added composition edges:
AuthenticationConfiguration→Configuration.authenticationDatabaseConfiguration/InferenceConfiguration/QuotaHandlersConfiguration/ConversationHistoryConfiguration/CORSConfiguration/TLSConfiguration
and the newQuotaSchedulerConfigurationclass composed intoQuotaHandlersConfiguration.scheduleraccurately reflect how the config models relate.
QuotaSchedulerConfigurationis also shown as extendingConfigurationBase, which is consistent with the repo guideline that config models derive fromConfigurationBase. Based on learnings, this is the right pattern.Also applies to: 140-156, 163-172
Description
LCORE-973: updated generated doc
Type of change
Tools used to create PR
Identify any AI code assistants used in this PR (for transparency and review context)
Related Tickets & Documents
Summary by CodeRabbit
Release Notes
Documentation
Style
✏️ Tip: You can customize this high-level summary in your review settings.