LCORE-1356: fixed OpenAPI.md file#1240
Merged
tisnik merged 2 commits intolightspeed-core:mainfrom Mar 1, 2026
Merged
Conversation
Contributor
WalkthroughThis change substantially restructures and expands the OpenAPI specification documentation by adding a comprehensive endpoint listing table, standardizing response schemas across endpoints with consistent error codes (403, 500, 422, 503), reorganizing endpoint descriptions, and normalizing formatting throughout the document. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 |
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/openapi.md (1)
3057-3122:⚠️ Potential issue | 🟡 MinorFix broken response table formatting.
The response table for the
/readinessendpoint has malformed structure. Examples are incorrectly embedded within table cells, causing the table to break. Lines 3088, 3105, and 3122 show trailing|characters that terminate the table rows improperly.The table should either:
- Move examples outside the table (recommended for readability), or
- Use proper markdown table cell escaping if examples must stay inline
This same issue appears in several other endpoints (
/liveness,/authorized,/metrics).📝 Example fix for readiness endpoint
| Status Code | Description | Component | |-------------|-------------|-----------| | 200 | Successful response | [ReadinessResponse](`#readinessresponse`) | -| 401 | Unauthorized | [UnauthorizedResponse](`#unauthorizedresponse`) +| 401 | Unauthorized | [UnauthorizedResponse](`#unauthorizedresponse`) | +| 403 | Permission denied | [ForbiddenResponse](`#forbiddenresponse`) | +| 503 | Service unavailable | [ServiceUnavailableResponse](`#serviceunavailableresponse`) | Examples +```json +{ + "detail": { + "cause": "No Authorization header found", + "response": "Missing or invalid credentials provided by client" + } +} +``` - -Examples - - - - - -```json -{ - "detail": { - "cause": "No Authorization header found", - "response": "Missing or invalid credentials provided by client" - } -} -``` - - - - - -```json -{ - "detail": { - "cause": "No token found in Authorization header", - "response": "Missing or invalid credentials provided by client" - } -} -``` - | -| 403 | Permission denied | [ForbiddenResponse](`#forbiddenresponse`)Apply similar fixes to
/liveness(lines 3123-3186),/authorized(lines 3187-3255), and/metrics(lines 3256-3361).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/openapi.md` around lines 3057 - 3122, The response table rows for the /readiness (and similarly /liveness, /authorized, /metrics) endpoints are broken because JSON Examples are embedded inside table cells and trailing " |" ended rows; to fix, remove the inline Examples blocks from inside the markdown table and place each example as a fenced code block immediately after the table row for the corresponding status code (or alternatively escape pipe characters if you must keep them inline), updating the ReadinessResponse/UnauthorizedResponse/ForbiddenResponse/ServiceUnavailableResponse rows so the table contains only the Status Code, Description, and Component columns and the example JSON blocks follow the table.
🧹 Nitpick comments (1)
docs/openapi.md (1)
113-114: Minor wording improvement suggestion.The description currently reads "Process GET requests to the /info endpoint, returning the service name, version and Llama-stack version."
Consider adding a comma for better readability: "returning the service name, version**,** and Llama-stack version" (Oxford comma).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/openapi.md` around lines 113 - 114, Update the GET /info operation description to include the Oxford comma: change the sentence that currently reads "Process GET requests to the /info endpoint, returning the service name, version and Llama-stack version." to "Process GET requests to the /info endpoint, returning the service name, version, and Llama-stack version." (locate the description for the /info endpoint in docs/openapi.md).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@docs/openapi.md`:
- Around line 3057-3122: The response table rows for the /readiness (and
similarly /liveness, /authorized, /metrics) endpoints are broken because JSON
Examples are embedded inside table cells and trailing " |" ended rows; to fix,
remove the inline Examples blocks from inside the markdown table and place each
example as a fenced code block immediately after the table row for the
corresponding status code (or alternatively escape pipe characters if you must
keep them inline), updating the
ReadinessResponse/UnauthorizedResponse/ForbiddenResponse/ServiceUnavailableResponse
rows so the table contains only the Status Code, Description, and Component
columns and the example JSON blocks follow the table.
---
Nitpick comments:
In `@docs/openapi.md`:
- Around line 113-114: Update the GET /info operation description to include the
Oxford comma: change the sentence that currently reads "Process GET requests to
the /info endpoint, returning the service name, version and Llama-stack
version." to "Process GET requests to the /info endpoint, returning the service
name, version, and Llama-stack version." (locate the description for the /info
endpoint in docs/openapi.md).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
LCORE-1356: fixed OpenAPI.md file
Type of change
Tools used to create PR
Related Tickets & Documents
Summary by CodeRabbit