LCORE-2572: Up to date OpenAPI documentation for /config and health endpoints#1934
Conversation
WalkthroughDocstrings for the ChangesEndpoint error documentation
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
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: 7
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/openapi.json`:
- Line 6713: The docs/openapi.json file is a generated artifact that has drifted
from the source schema and is causing CI failures. Rather than manually editing
this file, regenerate it completely from the source code using the appropriate
OpenAPI generation tool (typically a command that extracts docstrings from the
FastAPI application). After regeneration, ensure the descriptions for the
/config, /readiness, and /liveness endpoints match the source-generated schema
exactly, then commit the regenerated artifact to resolve the schema drift.
In `@docs/openapi.md`:
- Around line 4811-4817: The "### Raises:" section documents HTTP status codes
401, 403, 500, and 503 for the `/readiness` endpoint, but the response table
below does not include the 500 status code. Update the response table to include
all status codes mentioned in the Raises section (both 500 and 503).
Additionally, add a blank line before the "### Raises:" heading to comply with
the MD022 markdown linting rule for blank lines before headings.
- Around line 4899-4905: Add a blank line before the "Raises" heading to comply
with the MD022 markdown linting rule which requires blank lines before headings.
Additionally, the response table below the Raises section is missing entries for
the 500 and 503 status codes that are documented in the Raises section. Update
the response table to include both the 500 status code response with a detail
object containing response and cause fields (for wrong or incomplete service
configuration), and the 503 status code response with a detail object containing
response and cause fields (for unable to connect to Llama Stack). This ensures
the response documentation is synchronized with the Raises section.
- Around line 3038-3044: The `/v1/config` endpoint documentation has two issues:
the Raises section documents HTTP status code 503 for Llama Stack connection
failures, but the response table below it does not include this status code (it
stops at 500). Add a blank line before the "### Raises:" heading to comply with
markdown rule MD022, and then update the response table below the Raises section
to include the 503 status code with its description to match what is documented
in the Raises section.
In `@src/app/endpoints/config.py`:
- Around line 54-60: The Raises sections in the docstrings for all three
endpoints have incomplete documentation of error response detail structures.
Currently, the detail object containing response and cause fields is documented
only for status codes 500 and 503, but all four error statuses (401, 403, 500,
503) use error response models that always include these fields. Update the
docstring Raises sections at the following locations to document the
detail.response and detail.cause fields for all four error statuses: In
src/app/endpoints/config.py lines 54-60, add detail object structure
documentation to both the 401 and 403 HTTPException entries. In
src/app/endpoints/health.py lines 130-136, add detail object structure
documentation to both the 401 and 403 HTTPException entries. In
src/app/endpoints/health.py lines 188-194, add detail object structure
documentation to both the 401 and 403 HTTPException entries. Ensure the
documentation format is consistent across all three endpoints and accurately
reflects that all error responses contain response and cause fields.
In `@src/app/endpoints/health.py`:
- Around line 130-136: The docstring in the Raises section documents
HTTPException with status 500, but the `get_readiness_responses` responses
dictionary does not include a 500 status entry. To fix this mismatch, either
remove the status 500 entry from the docstring Raises section (lines 130-136),
or add a 500 status response entry to the `get_readiness_responses` dictionary
at line 36 by including `500:
InternalServerErrorResponse.openapi_response(examples=[...])` to ensure the
OpenAPI schema matches the documented behavior, following the pattern used for
status 500 in the /config endpoint.
- Around line 188-194: The Raises section of the docstring documents
HTTPException with status 500 as a possible response, but the
`get_liveness_responses` dictionary does not include 500 in its responses dict,
causing a mismatch with the OpenAPI schema generation. Either remove the
HTTPException with status 500 from the docstring's Raises section, or add status
500 to the `get_liveness_responses` responses dictionary by including an
InternalServerErrorResponse entry with appropriate examples to match the pattern
used for similar error responses elsewhere in the codebase.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: fdd0ec0a-6605-4e85-bf4c-f859f7284f12
📒 Files selected for processing (4)
docs/openapi.jsondocs/openapi.mdsrc/app/endpoints/config.pysrc/app/endpoints/health.py
📜 Review details
⏰ 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). (15)
- GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-on-pull-request
- GitHub Check: Konflux kflux-prd-rh02 / lightspeed-stack-0-6-on-pull-request
- GitHub Check: mypy
- GitHub Check: integration_tests (3.13)
- GitHub Check: integration_tests (3.12)
- GitHub Check: build-pr
- GitHub Check: Pylinter
- GitHub Check: unit_tests (3.12)
- GitHub Check: E2E: library mode / ci / group 3
- GitHub Check: E2E: server mode / ci / group 2
- GitHub Check: E2E Tests for Lightspeed Evaluation job
- GitHub Check: E2E: server mode / ci / group 3
- GitHub Check: E2E: library mode / ci / group 2
- GitHub Check: E2E: library mode / ci / group 1
- GitHub Check: E2E: server mode / ci / group 1
🧰 Additional context used
📓 Path-based instructions (2)
src/**/*.py
📄 CodeRabbit inference engine (AGENTS.md)
src/**/*.py: Use absolute imports for internal modules:from authentication import get_auth_dependency
Llama Stack imports: Usefrom llama_stack_client import AsyncLlamaStackClient
Checkconstants.pyfor shared constants before defining new ones
All modules must start with descriptive docstrings explaining purpose
Uselogger = get_logger(__name__)fromlog.pyfor module logging
All functions must have complete type annotations for parameters and return types, use modern syntax (str | int), and include descriptive docstrings
Use snake_case with descriptive, action-oriented names for functions (get_, validate_, check_)
Avoid in-place parameter modification anti-patterns; return new data structures instead of modifying function parameters
Useasync deffor I/O operations and external API calls
Use standard log levels with clear purposes:debug()for diagnostic info,info()for program execution,warning()for unexpected events,error()for serious problems
All classes must have descriptive docstrings explaining purpose and use PascalCase with standard suffixes:Configuration,Error/Exception,Resolver,Interface
Abstract classes must use ABC with@abstractmethoddecorators
Follow Google Python docstring conventions with required sections: Parameters, Returns, Raises, and Attributes for classes
Files:
src/app/endpoints/health.pysrc/app/endpoints/config.py
src/app/**/*.py
📄 CodeRabbit inference engine (AGENTS.md)
src/app/**/*.py: FastAPI dependencies: Import fromfastapimodule forAPIRouter,HTTPException,Request,status,Depends
Use FastAPIHTTPExceptionwith appropriate status codes for API endpoints and handleAPIConnectionErrorfrom Llama Stack
Files:
src/app/endpoints/health.pysrc/app/endpoints/config.py
🧠 Learnings (1)
📚 Learning: 2026-04-06T20:18:07.852Z
Learnt from: major
Repo: lightspeed-core/lightspeed-stack PR: 1463
File: src/app/endpoints/rlsapi_v1.py:266-271
Timestamp: 2026-04-06T20:18:07.852Z
Learning: In the lightspeed-stack codebase, within `src/app/endpoints/` inference/MCP endpoints, treat `tools: Optional[list[Any]]` in MCP tool definitions as an intentional, consistent typing pattern (used across `query`, `responses`, `streaming_query`, `rlsapi_v1`). Do not raise or suggest this as a typing issue during code review; changing it in isolation could break endpoint typing consistency across the codebase.
Applied to files:
src/app/endpoints/health.pysrc/app/endpoints/config.py
🪛 GitHub Actions: OpenAPI (Spectral) / 0_spectral.txt
docs/openapi.json
[error] 1-1: CI step failed: docs/openapi.json is out of date. Regenerate with: uv run scripts/generate_openapi_schema.py docs/openapi.json (diff -u between docs/openapi.json and generated schema returned non-zero).
🪛 GitHub Actions: OpenAPI (Spectral) / spectral
docs/openapi.json
[error] 1-1: OpenAPI schema is out of date. Step failed: diff -u docs/openapi.json /tmp/openapi-generated.json. Regenerate with: uv run scripts/generate_openapi_schema.py docs/openapi.json
🪛 markdownlint-cli2 (0.22.1)
docs/openapi.md
[warning] 3038-3038: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 4811-4811: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 4899-4899: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
| ], | ||
| "summary": "Config Endpoint Handler", | ||
| "description": "Handle requests to the /config endpoint.\n\nProcess GET requests to the /config endpoint and returns the\ncurrent service configuration.\n\nEnsures the application configuration is loaded before returning it.\n\n### Parameters:\n- request: The incoming HTTP request.\n- auth: Authentication tuple from the auth dependency.\n\n### Returns:\n- ConfigurationResponse: The loaded service configuration response.", | ||
| "description": "Handle requests to the /config endpoint.\n\nProcess GET requests to the /config endpoint and returns the\ncurrent service configuration.\n\nEnsures the application configuration is loaded before returning it.\n\n### Parameters:\n- request: The incoming HTTP request.\n- auth: Authentication tuple from the auth dependency.\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 500 and a detail object containing `response`\n and `cause` when service configuration is wrong or incomplete.\n- HTTPException: with status 503 and a detail object containing `response`\n and `cause` when unable to connect to Llama Stack.\n\n### Returns:\n- ConfigurationResponse: The loaded service configuration response.", |
There was a problem hiding this comment.
Regenerate OpenAPI artifact to resolve CI-blocking schema drift.
Line 6713 is part of a manually updated generated file, but CI shows docs/openapi.json is still out of date versus the generator output. Please regenerate and commit the full artifact so the documented /config, /readiness, and /liveness descriptions match source-generated schema exactly.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/openapi.json` at line 6713, The docs/openapi.json file is a generated
artifact that has drifted from the source schema and is causing CI failures.
Rather than manually editing this file, regenerate it completely from the source
code using the appropriate OpenAPI generation tool (typically a command that
extracts docstrings from the FastAPI application). After regeneration, ensure
the descriptions for the /config, /readiness, and /liveness endpoints match the
source-generated schema exactly, then commit the regenerated artifact to resolve
the schema drift.
Source: Pipeline failures
| ### Raises: | ||
| - HTTPException: with status 401 for unauthorized access. | ||
| - HTTPException: with status 403 if permission is denied. | ||
| - HTTPException: with status 500 and a detail object containing `response` | ||
| and `cause` when service configuration is wrong or incomplete. | ||
| - HTTPException: with status 503 and a detail object containing `response` | ||
| and `cause` when unable to connect to Llama Stack. |
There was a problem hiding this comment.
Sync the /v1/config Raises section with the response table.
503 is now documented here, but the response table below still stops at 500. Also insert a blank line before this heading to satisfy MD022.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 3038-3038: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/openapi.md` around lines 3038 - 3044, The `/v1/config` endpoint
documentation has two issues: the Raises section documents HTTP status code 503
for Llama Stack connection failures, but the response table below it does not
include this status code (it stops at 500). Add a blank line before the "###
Raises:" heading to comply with markdown rule MD022, and then update the
response table below the Raises section to include the 503 status code with its
description to match what is documented in the Raises section.
| ### Raises: | ||
| - HTTPException: with status 401 for unauthorized access. | ||
| - HTTPException: with status 403 if permission is denied. | ||
| - HTTPException: with status 500 and a detail object containing `response` | ||
| and `cause` when service configuration is wrong or incomplete. | ||
| - HTTPException: with status 503 and a detail object containing `response` | ||
| and `cause` when unable to connect to Llama Stack. |
There was a problem hiding this comment.
Sync the /readiness Raises section with the response table.
500 is documented here, but the response table below still only lists 503. Add the missing blank line before this heading for MD022.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 4811-4811: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/openapi.md` around lines 4811 - 4817, The "### Raises:" section
documents HTTP status codes 401, 403, 500, and 503 for the `/readiness`
endpoint, but the response table below does not include the 500 status code.
Update the response table to include all status codes mentioned in the Raises
section (both 500 and 503). Additionally, add a blank line before the "###
Raises:" heading to comply with the MD022 markdown linting rule for blank lines
before headings.
| ### Raises: | ||
| - HTTPException: with status 401 for unauthorized access. | ||
| - HTTPException: with status 403 if permission is denied. | ||
| - HTTPException: with status 500 and a detail object containing `response` | ||
| and `cause` when service configuration is wrong or incomplete. | ||
| - HTTPException: with status 503 and a detail object containing `response` | ||
| and `cause` when unable to connect to Llama Stack. |
There was a problem hiding this comment.
Sync the /liveness Raises section with the response table.
500/503 are documented here, but the response table below still omits both. Add the missing blank line before this heading for MD022.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 4899-4899: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/openapi.md` around lines 4899 - 4905, Add a blank line before the
"Raises" heading to comply with the MD022 markdown linting rule which requires
blank lines before headings. Additionally, the response table below the Raises
section is missing entries for the 500 and 503 status codes that are documented
in the Raises section. Update the response table to include both the 500 status
code response with a detail object containing response and cause fields (for
wrong or incomplete service configuration), and the 503 status code response
with a detail object containing response and cause fields (for unable to connect
to Llama Stack). This ensures the response documentation is synchronized with
the Raises section.
| ### Raises: | ||
| - HTTPException: with status 401 for unauthorized access. | ||
| - HTTPException: with status 403 if permission is denied. | ||
| - HTTPException: with status 500 and a detail object containing `response` | ||
| and `cause` when service configuration is wrong or incomplete. | ||
| - HTTPException: with status 503 and a detail object containing `response` | ||
| and `cause` when unable to connect to Llama Stack. |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial | ⚡ Quick win
Inconsistent documentation of detail structure in Raises sections across all three endpoints.
All three endpoints (config, readiness, liveness) document detail.response and detail.cause only for status codes 500 and 503, but all four error statuses (401, 403, 500, 503) use error response models that inherit from AbstractErrorResponse (per relevant_code_snippets, line 29-31), which always includes detail.response and detail.cause fields.
Either document the detail structure for all error statuses, or document it for none. For consistency with the error model contract, recommend documenting it for all four (401, 403, 500, 503).
src/app/endpoints/config.py#L54-L60: Mentiondetail.responseanddetail.causefor 401 and 403 as well.src/app/endpoints/health.py#L130-L136: Mentiondetail.responseanddetail.causefor 401 and 403 as well.src/app/endpoints/health.py#L188-L194: Mentiondetail.responseanddetail.causefor 401 and 403 as well.
📍 Affects 2 files
src/app/endpoints/config.py#L54-L60(this comment)src/app/endpoints/health.py#L130-L136src/app/endpoints/health.py#L188-L194
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/app/endpoints/config.py` around lines 54 - 60, The Raises sections in the
docstrings for all three endpoints have incomplete documentation of error
response detail structures. Currently, the detail object containing response and
cause fields is documented only for status codes 500 and 503, but all four error
statuses (401, 403, 500, 503) use error response models that always include
these fields. Update the docstring Raises sections at the following locations to
document the detail.response and detail.cause fields for all four error
statuses: In src/app/endpoints/config.py lines 54-60, add detail object
structure documentation to both the 401 and 403 HTTPException entries. In
src/app/endpoints/health.py lines 130-136, add detail object structure
documentation to both the 401 and 403 HTTPException entries. In
src/app/endpoints/health.py lines 188-194, add detail object structure
documentation to both the 401 and 403 HTTPException entries. Ensure the
documentation format is consistent across all three endpoints and accurately
reflects that all error responses contain response and cause fields.
| ### Raises: | ||
| - HTTPException: with status 401 for unauthorized access. | ||
| - HTTPException: with status 403 if permission is denied. | ||
| - HTTPException: with status 500 and a detail object containing `response` | ||
| and `cause` when service configuration is wrong or incomplete. | ||
| - HTTPException: with status 503 and a detail object containing `response` | ||
| and `cause` when unable to connect to Llama Stack. |
There was a problem hiding this comment.
Mismatch between documented Raises and responses decorator: status 500 not in responses dict.
The docstring documents HTTPException with status 500, but get_readiness_responses (line 36) does not include 500 in its responses dictionary. The responses dict controls the OpenAPI schema generation, so status 500 will not appear in the published API documentation even though the docstring claims it's possible.
Either remove 500 from the docstring Raises section, or add 500: InternalServerErrorResponse.openapi_response(examples=[...]) to the get_readiness_responses dict to match /config (line 31 in config.py).
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/app/endpoints/health.py` around lines 130 - 136, The docstring in the
Raises section documents HTTPException with status 500, but the
`get_readiness_responses` responses dictionary does not include a 500 status
entry. To fix this mismatch, either remove the status 500 entry from the
docstring Raises section (lines 130-136), or add a 500 status response entry to
the `get_readiness_responses` dictionary at line 36 by including `500:
InternalServerErrorResponse.openapi_response(examples=[...])` to ensure the
OpenAPI schema matches the documented behavior, following the pattern used for
status 500 in the /config endpoint.
| ### Raises: | ||
| - HTTPException: with status 401 for unauthorized access. | ||
| - HTTPException: with status 403 if permission is denied. | ||
| - HTTPException: with status 500 and a detail object containing `response` | ||
| and `cause` when service configuration is wrong or incomplete. | ||
| - HTTPException: with status 503 and a detail object containing `response` | ||
| and `cause` when unable to connect to Llama Stack. |
There was a problem hiding this comment.
Mismatch between documented Raises and responses decorator: status 500 not in responses dict.
The docstring documents HTTPException with status 500, but get_liveness_responses (line 45) does not include 500 in its responses dictionary. The responses dict controls the OpenAPI schema generation, so status 500 will not appear in the published API documentation even though the docstring claims it's possible.
Either remove 500 from the docstring Raises section, or add 500: InternalServerErrorResponse.openapi_response(examples=[...]) to the get_liveness_responses dict to match /config (line 31 in config.py).
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/app/endpoints/health.py` around lines 188 - 194, The Raises section of
the docstring documents HTTPException with status 500 as a possible response,
but the `get_liveness_responses` dictionary does not include 500 in its
responses dict, causing a mismatch with the OpenAPI schema generation. Either
remove the HTTPException with status 500 from the docstring's Raises section, or
add status 500 to the `get_liveness_responses` responses dictionary by including
an InternalServerErrorResponse entry with appropriate examples to match the
pattern used for similar error responses elsewhere in the codebase.
1 participant
Description
LCORE-2572: Up to date OpenAPI documentation for /config and health endpoints
Type of change
Tools used to create PR
Related Tickets & Documents
Summary by CodeRabbit