LCORE-304: OpenAPI documentation in Markdown #259
Conversation
WalkthroughThe changes update the README to include a link to a new OpenAPI markdown documentation file and add this comprehensive OpenAPI specification ( Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant API Server
Client->>API Server: GET /info
API Server-->>Client: InfoResponse
Client->>API Server: GET /models
API Server-->>Client: ModelsResponse
Client->>API Server: POST /query (QueryRequest)
API Server-->>Client: QueryResponse
Client->>API Server: POST /feedback (FeedbackRequest)
API Server-->>Client: FeedbackResponse
Client->>API Server: GET /conversation/{id}
API Server-->>Client: ConversationResponse
Client->>API Server: DELETE /conversation/{id}
API Server-->>Client: ConversationDeleteResponse
Client->>API Server: GET /ready
API Server-->>Client: ReadinessResponse
Client->>API Server: GET /live
API Server-->>Client: LivenessResponse
Possibly related PRs
Poem
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/openapi.md (1)
309-314: Specify a language on fenced code blocksThe YAML example is missing the language tag, triggering
MD040.
Addyamlto enable syntax highlighting and keep linters happy:-``` +```yaml kind: Pod metadata: name: private-reg
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
README.md(1 hunks)docs/openapi.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
docs/openapi.md
28-28: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
29-29: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
29-29: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
44-44: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
45-45: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
45-45: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
60-60: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
61-61: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
62-62: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
81-81: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
82-82: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
83-83: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
84-84: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
85-85: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
86-86: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
88-88: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
89-89: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
89-89: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
109-109: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
110-110: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
110-110: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
125-125: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
126-126: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
127-127: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
156-156: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
157-157: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
158-158: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
159-159: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
160-160: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
161-161: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
162-162: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
163-163: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
163-163: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
181-181: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
182-182: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
182-182: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
202-202: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
203-203: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
206-206: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
207-207: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
207-207: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
227-227: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
228-228: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
231-231: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
232-232: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
232-232: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
247-247: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
248-248: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
249-249: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
250-250: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
250-250: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
265-265: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
266-266: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
267-267: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
268-268: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
268-268: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
283-283: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
284-284: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
285-285: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
286-286: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
287-287: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
288-288: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
288-288: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
309-309: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ 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). (1)
- GitHub Check: build-pr
🔇 Additional comments (2)
docs/openapi.md (1)
8-12: Fix the first table’s pipe alignment and trailing pipesTables are rendered incorrectly because each row lacks the closing
|.
This breaks both GitHub preview and any auto-generated docs (mkdocs, MDX, etc.) and is the root cause of the first wave ofMD055 / MD056 / MD058linter errors.-| URL | Description | -|-----|-------------| +| URL | Description | +|-----|-------------|Apply the same pattern to every table in the document to silence markdown-lint and guarantee proper rendering.
A quickmarkdownlint --fixpass will catch the remaining instances.Likely an incorrect or invalid review comment.
README.md (1)
234-235: Addition looks goodThe new bullet cleanly surfaces the Markdown spec beside the JSON one; no issues spotted.
| ### ✅ Responses | ||
|
|
||
| | Status Code | Description | Component | | ||
| |-------------|-------------|-----------| | ||
| | 200 | Successful Response | string | ||
| | | ||
| ## GET `/v1/info` | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Rows with missing columns leave the “Component” cell empty
Several response tables declare three columns but supply data for only one, producing an “Actual: 1” linter error and a malformed layout. Either:
- Populate the missing two cells, or
- Drop the empty columns if they’re not needed.
Example fix:
-| 200 | Successful Response | [InfoResponse](#inforesponse)
+| 200 | Successful Response | [InfoResponse](#inforesponse) |Resolve this pattern across the file to restore table integrity.
Committable suggestion skipped: line range outside the PR's diff.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
28-28: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
29-29: Table column count
Expected: 3; Actual: 1; Too few cells, row will be missing data
(MD056, table-column-count)
29-29: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In docs/openapi.md around lines 24 to 31, the response tables declare three
columns but only provide data for one, leaving the "Component" column empty and
causing linter errors and layout issues. To fix this, either fill in the missing
"Description" and "Component" cells with appropriate content or remove the extra
columns if they are unnecessary, ensuring all rows have the correct number of
columns to maintain table integrity.
1 participant
Description
LCORE-304: OpenAPI documentation in Markdown
Type of change
Related Tickets & Documents
Summary by CodeRabbit