Skip to content

LCORE-2572: Up to date OpenAPI documentation for /config and health endpoints #1934

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 4 commits into from
Jun 16, 2026
Merged

LCORE-2572: Up to date OpenAPI documentation for /config and health endpoints #1934

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3e2aca9
Updated description for /config endpoint
tisnik Jun 16, 2026
f13abb3
Updated description for /readines endpoint
tisnik Jun 16, 2026
8c0aeb1
Updated description for /livenes endpoint
tisnik Jun 16, 2026
197b4ea
Regenerated OpenAPI documentation
tisnik Jun 16, 2026
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
6 changes: 3 additions & 3 deletions docs/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6710,7 +6710,7 @@
"config"
],
"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.",

@coderabbitai coderabbitai Bot Jun 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

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

"operationId": "config_endpoint_handler_v1_config_get",
"responses": {
"200": {
Expand Down Expand Up @@ -9964,7 +9964,7 @@
"health"
],
"summary": "Readiness Probe Get Method",
"description": "Handle the readiness probe endpoint, returning service readiness.\n\nIf any provider reports an error status, responds with HTTP 503\nand details of unhealthy providers; otherwise, indicates the\nservice is ready.\n\n### Parameters:\n- response: The outgoing HTTP response (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Returns:\n- ReadinessResponse: Object with `ready` indicating overall readiness,\n `reason` explaining the outcome, and `providers` containing the list of\n unhealthy ProviderHealthStatus entries (empty when ready).",
"description": "Handle the readiness probe endpoint, returning service readiness.\n\nIf any provider reports an error status, responds with HTTP 503\nand details of unhealthy providers; otherwise, indicates the\nservice is ready.\n\n### Parameters:\n- response: The outgoing HTTP response (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\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- ReadinessResponse: Object with `ready` indicating overall readiness,\n `reason` explaining the outcome, and `providers` containing the list of\n unhealthy ProviderHealthStatus entries (empty when ready).",
"operationId": "readiness_probe_get_method_readiness_get",
"responses": {
"200": {
Expand Down Expand Up @@ -10115,7 +10115,7 @@
"health"
],
"summary": "Liveness Probe Get Method",
"description": "Return the liveness status of the service.\n\n### Parameters:\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Returns:\n- LivenessResponse: Indicates that the service is alive.",
"description": "Return the liveness status of the service.\n\n### Parameters:\n- auth: Authentication tuple from the auth dependency (used by middleware).\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- LivenessResponse: Indicates that the service is alive.",
"operationId": "liveness_probe_get_method_liveness_get",
"responses": {
"200": {
Expand Down
24 changes: 24 additions & 0 deletions docs/openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3035,6 +3035,14 @@ Ensures the application configuration is loaded before returning it.
- request: The incoming HTTP request.
- auth: Authentication tuple from the auth dependency.

### 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.
Comment on lines +3038 to +3044

@coderabbitai coderabbitai Bot Jun 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

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.


### Returns:
- ConfigurationResponse: The loaded service configuration response.

Expand Down Expand Up @@ -4800,6 +4808,14 @@ service is ready.
- response: The outgoing HTTP response (used by middleware).
- auth: Authentication tuple from the auth dependency (used by middleware).

### 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.
Comment on lines +4811 to +4817

@coderabbitai coderabbitai Bot Jun 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

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.


### Returns:
- ReadinessResponse: Object with `ready` indicating overall readiness,
`reason` explaining the outcome, and `providers` containing the list of
Expand Down Expand Up @@ -4880,6 +4896,14 @@ Return the liveness status of the service.
### Parameters:
- auth: Authentication tuple from the auth dependency (used by middleware).

### 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.
Comment on lines +4899 to +4905

@coderabbitai coderabbitai Bot Jun 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

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.


### Returns:
- LivenessResponse: Indicates that the service is alive.

Expand Down
8 changes: 8 additions & 0 deletions src/app/endpoints/config.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,14 @@ async def config_endpoint_handler(
- request: The incoming HTTP request.
- auth: Authentication tuple from the auth dependency.

### 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.
Comment on lines +54 to +60

@coderabbitai coderabbitai Bot Jun 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🧹 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: Mention detail.response and detail.cause for 401 and 403 as well.
  • src/app/endpoints/health.py#L130-L136: Mention detail.response and detail.cause for 401 and 403 as well.
  • src/app/endpoints/health.py#L188-L194: Mention detail.response and detail.cause for 401 and 403 as well.
📍 Affects 2 files
  • src/app/endpoints/config.py#L54-L60 (this comment)
  • src/app/endpoints/health.py#L130-L136
  • src/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.


### Returns:
- ConfigurationResponse: The loaded service configuration response.
"""
Expand Down
16 changes: 16 additions & 0 deletions src/app/endpoints/health.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,14 @@ async def readiness_probe_get_method(
- response: The outgoing HTTP response (used by middleware).
- auth: Authentication tuple from the auth dependency (used by middleware).

### 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.
Comment on lines +130 to +136

@coderabbitai coderabbitai Bot Jun 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

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.


### Returns:
- ReadinessResponse: Object with `ready` indicating overall readiness,
`reason` explaining the outcome, and `providers` containing the list of
Expand Down Expand Up @@ -177,6 +185,14 @@ async def liveness_probe_get_method(
### Parameters:
- auth: Authentication tuple from the auth dependency (used by middleware).

### 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.
Comment on lines +188 to +194

@coderabbitai coderabbitai Bot Jun 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

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.


### Returns:
- LivenessResponse: Indicates that the service is alive.
"""
Expand Down
Loading