Skip to content

Regenerated OpenAPI spec + doc #451

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
merged 1 commit into from
Aug 26, 2025
Merged

Regenerated OpenAPI spec + doc #451

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
145 changes: 134 additions & 11 deletions docs/openapi.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -698,6 +698,50 @@
},
"components": {
"schemas": {
"AccessRule": {
"properties": {
"role": {
"type": "string",
"title": "Role"
},
Comment on lines 699 to +706
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 26, 2025

Choose a reason for hiding this comment

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

⚠️ Potential issue

Spec declares 401/403 but defines no securitySchemes or per-operation security; add bearer JWT scheme and apply to protected endpoints.

Given the presence of JWK/JWT configuration and 401/403 responses, the spec should declare an auth mechanism to be usable by code generators and API portals.

  • Add a bearer security scheme under components.
  • Attach security requirements to operations that require auth (e.g., POST /v1/query, POST /v1/streaming_query, GET/DELETE conversation endpoints, POST /v1/feedback, GET /v1/conversations, POST /authorized if applicable).

Minimal addition:

@@
   "components": {
     "schemas": {
       ...
     }
+    ,
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT",
+        "description": "JWT Bearer token obtained via your identity provider"
+      }
+    }
   }

Then, per operation (example for POST /v1/query):

 "post": {
   "tags": ["query"],
   "summary": "Query Endpoint Handler",
+  "security": [ { "bearerAuth": [] } ],
   ...

Without these, clients won’t know how to authenticate.

Also applies to: 940-1012, 1556-1570, 1579-1602

🤖 Prompt for AI Agents 
In docs/openapi.json around lines 699-706 (and also review ranges ~940-1012,
1556-1570, 1579-1602), the OpenAPI spec lists 401/403 responses but defines no
security schemes or per-operation security; add a bearer JWT security scheme
under components.securitySchemes (type: http, scheme: bearer, bearerFormat: JWT)
and then attach security requirements to each protected operation (e.g., POST
/v1/query, POST /v1/streaming_query, GET/DELETE conversation endpoints, POST
/v1/feedback, GET /v1/conversations, POST /authorized if applicable) by adding a
security array referencing the bearer scheme so clients and code generators know
how to authenticate.

"actions": {
"items": {
"$ref": "#/components/schemas/Action"
},
"type": "array",
"title": "Actions"
}
},
"type": "object",
"required": [
"role",
"actions"
],
"title": "AccessRule",
"description": "Rule defining what actions a role can perform."
},
"Action": {
"type": "string",
"enum": [
"admin",
"list_other_conversations",
"read_other_conversations",
"query_other_conversations",
"delete_other_conversations",
"query",
"streaming_query",
"get_conversation",
"list_conversations",
"delete_conversation",
"feedback",
"get_models",
"get_metrics",
"get_config",
"info"
],
"title": "Action",
"description": "Available actions in the system."
},
"Attachment": {
"properties": {
"attachment_type": {
Expand All @@ -721,7 +765,7 @@
"title": "Content",
"description": "The actual attachment content",
"examples": [
"warning: quota exceed"
"warning: quota exceeded"
]
}
},
Expand All @@ -732,7 +776,7 @@
"content"
],
"title": "Attachment",
"description": "Model representing an attachment that can be send from UI as part of query.\n\nList of attachments can be optional part of 'query' request.\n\nAttributes:\n attachment_type: The attachment type, like \"log\", \"configuration\" etc.\n content_type: The content type as defined in MIME standard\n content: The actual attachment content\n\nYAML attachments with **kind** and **metadata/name** attributes will\nbe handled as resources with specified name:\n```\nkind: Pod\nmetadata:\n name: private-reg\n```",
"description": "Model representing an attachment that can be send from the UI as part of query.\n\nA list of attachments can be an optional part of 'query' request.\n\nAttributes:\n attachment_type: The attachment type, like \"log\", \"configuration\" etc.\n content_type: The content type as defined in MIME standard\n content: The actual attachment content\n\nYAML attachments with **kind** and **metadata/name** attributes will\nbe handled as resources with the specified name:\n```\nkind: Pod\nmetadata:\n name: private-reg\n```",
"examples": [
{
"attachment_type": "log",
Expand Down Expand Up @@ -803,6 +847,20 @@
"title": "AuthenticationConfiguration",
"description": "Authentication configuration."
},
"AuthorizationConfiguration": {
"properties": {
"access_rules": {
"items": {
"$ref": "#/components/schemas/AccessRule"
},
"type": "array",
"title": "Access Rules"
}
},
"type": "object",
"title": "AuthorizationConfiguration",
"description": "Authorization configuration."
},
"AuthorizedResponse": {
"properties": {
"user_id": {
Expand Down Expand Up @@ -917,6 +975,16 @@
"skip_tls_verification": false
}
},
"authorization": {
"anyOf": [
{
"$ref": "#/components/schemas/AuthorizationConfiguration"
},
{
"type": "null"
}
]
},
"customization": {
"anyOf": [
{
Expand Down Expand Up @@ -1040,7 +1108,7 @@
"conversation_id"
],
"title": "ConversationDetails",
"description": "Model representing the details of a user conversation.\n\nAttributes:\n conversation_id: The conversation ID (UUID).\n created_at: When the conversation was created.\n last_message_at: When the last message was sent.\n message_count: Number of user messages in the conversation.\n model: The model used for the conversation.\n\nExample:\n ```python\n conversation = ConversationSummary(\n conversation_id=\"123e4567-e89b-12d3-a456-426614174000\"\n created_at=\"2024-01-01T00:00:00Z\",\n last_message_at=\"2024-01-01T00:05:00Z\",\n message_count=5,\n model=\"gemini/gemini-2.0-flash\"\n )\n ```"
"description": "Model representing the details of a user conversation.\n\nAttributes:\n conversation_id: The conversation ID (UUID).\n created_at: When the conversation was created.\n last_message_at: When the last message was sent.\n message_count: Number of user messages in the conversation.\n last_used_model: The last model used for the conversation.\n last_used_provider: The provider of the last used model.\n\nExample:\n ```python\n conversation = ConversationDetails(\n conversation_id=\"123e4567-e89b-12d3-a456-426614174000\"\n created_at=\"2024-01-01T00:00:00Z\",\n last_message_at=\"2024-01-01T00:05:00Z\",\n message_count=5,\n last_used_model=\"gemini/gemini-2.0-flash\",\n last_used_provider=\"gemini\",\n )\n ```"
},
"ConversationResponse": {
"properties": {
Expand Down Expand Up @@ -1101,22 +1169,24 @@
"conversations"
],
"title": "ConversationsListResponse",
"description": "Model representing a response for listing conversations of a user.\n\nAttributes:\n conversations: List of conversation details associated with the user.\n\nExample:\n ```python\n conversations_list = ConversationsListResponse(\n conversations=[\n ConversationDetails(\n conversation_id=\"123e4567-e89b-12d3-a456-426614174000\",\n created_at=\"2024-01-01T00:00:00Z\",\n last_message_at=\"2024-01-01T00:05:00Z\",\n message_count=5,\n model=\"gemini/gemini-2.0-flash\"\n ),\n ConversationDetails(\n conversation_id=\"456e7890-e12b-34d5-a678-901234567890\"\n created_at=\"2024-01-01T01:00:00Z\",\n message_count=2,\n model=\"gemini/gemini-2.5-flash\"\n )\n ]\n )\n ```",
"description": "Model representing a response for listing conversations of a user.\n\nAttributes:\n conversations: List of conversation details associated with the user.\n\nExample:\n ```python\n conversations_list = ConversationsListResponse(\n conversations=[\n ConversationDetails(\n conversation_id=\"123e4567-e89b-12d3-a456-426614174000\",\n created_at=\"2024-01-01T00:00:00Z\",\n last_message_at=\"2024-01-01T00:05:00Z\",\n message_count=5,\n last_used_model=\"gemini/gemini-2.0-flash\",\n last_used_provider=\"gemini\",\n ),\n ConversationDetails(\n conversation_id=\"456e7890-e12b-34d5-a678-901234567890\"\n created_at=\"2024-01-01T01:00:00Z\",\n message_count=2,\n last_used_model=\"gemini/gemini-2.0-flash\",\n last_used_provider=\"gemini\",\n )\n ]\n )\n ```",
"examples": [
{
"conversations": [
{
"conversation_id": "123e4567-e89b-12d3-a456-426614174000",
"created_at": "2024-01-01T00:00:00Z",
"last_message_at": "2024-01-01T00:05:00Z",
"message_count": 5,
"model": "gemini/gemini-2.0-flash"
"last_used_model": "gemini/gemini-2.0-flash",
"last_used_provider": "gemini",
"message_count": 5
},
{
"conversation_id": "456e7890-e12b-34d5-a678-901234567890",
"created_at": "2024-01-01T01:00:00Z",
"message_count": 2,
"model": "gemini/gemini-2.5-flash"
"last_used_model": "gemini/gemini-2.5-flash",
"last_used_provider": "gemini",
"message_count": 2
}
]
}
Expand Down Expand Up @@ -1464,14 +1534,24 @@
"version"
],
"title": "InfoResponse",
"description": "Model representing a response to a info request.\n\nAttributes:\n name: Service name.\n version: Service version.\n\nExample:\n ```python\n info_response = InfoResponse(\n name=\"Lightspeed Stack\",\n version=\"1.0.0\",\n )\n ```",
"description": "Model representing a response to an info request.\n\nAttributes:\n name: Service name.\n version: Service version.\n\nExample:\n ```python\n info_response = InfoResponse(\n name=\"Lightspeed Stack\",\n version=\"1.0.0\",\n )\n ```",
"examples": [
{
"name": "Lightspeed Stack",
"version": "1.0.0"
}
]
},
"JsonPathOperator": {
"type": "string",
"enum": [
"equals",
"contains",
"in"
],
"title": "JsonPathOperator",
"description": "Supported operators for JSONPath evaluation."
},
Comment on lines +1546 to +1554
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 26, 2025

Choose a reason for hiding this comment

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

🛠️ Refactor suggestion

⚠️ Potential issue

JwtRoleRule.value is required but has no type; define explicit schema and document operator-dependent expectations.

Right now, "value" (Lines 1618–1619) is title-only with no type, yet it is required (Lines 1630–1634). This is too permissive and will likely fail client generation or allow invalid configs at runtime.

Recommend constraining "value" and clarifying semantics:

   "value": {
-    "title": "Value"
+    "title": "Value",
+    "description": "Literal to compare for 'equals'/'contains', or array of candidates for 'in'.",
+    "anyOf": [
+      { "type": "string" },
+      { "type": "number" },
+      { "type": "boolean" },
+      { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+      { "type": "array", "items": { "type": "number" }, "minItems": 1 }
+    ]
   },

Optionally, add a note to "operator" clarifying that "in" expects an array, while "equals"/"contains" expect scalars. Without this, validators and UIs can’t guide users correctly.

Also applies to: 1603-1637

🤖 Prompt for AI Agents 
In docs/openapi.json around lines 1546 to 1554, JwtRoleRule.value is currently
only a title and left untyped while marked required elsewhere; update the schema
to explicitly declare allowed types and document operator-dependent
expectations: set "value" to allow either a string (for "equals" and "contains")
or an array of strings (for "in") — preferably via a oneOf that includes
{"type":"string"} and {"type":"array","items":{"type":"string"}} — and add a
clear description noting that "in" expects an array and "equals"/"contains"
expect a scalar; ensure the required list still includes "value" and adjust any
examples or validators to match the new schema.

"JwkConfiguration": {
"properties": {
"url": {
Expand All @@ -1484,7 +1564,8 @@
"$ref": "#/components/schemas/JwtConfiguration",
"default": {
"user_id_claim": "user_id",
"username_claim": "username"
"username_claim": "username",
"role_rules": []
}
}
},
Expand All @@ -1506,12 +1587,54 @@
"type": "string",
"title": "Username Claim",
"default": "username"
},
"role_rules": {
"items": {
"$ref": "#/components/schemas/JwtRoleRule"
},
"type": "array",
"title": "Role Rules"
}
},
"type": "object",
"title": "JwtConfiguration",
"description": "JWT configuration."
},
"JwtRoleRule": {
"properties": {
"jsonpath": {
"type": "string",
"title": "Jsonpath"
},
"operator": {
"$ref": "#/components/schemas/JsonPathOperator"
},
"negate": {
"type": "boolean",
"title": "Negate",
"default": false
},
"value": {
"title": "Value"
},
"roles": {
"items": {
"type": "string"
},
"type": "array",
"title": "Roles"
}
},
"type": "object",
"required": [
"jsonpath",
"operator",
"value",
"roles"
],
"title": "JwtRoleRule",
"description": "Rule for extracting roles from JWT claims."
},
"LivenessResponse": {
"properties": {
"alive": {
Expand Down Expand Up @@ -2237,4 +2360,4 @@
}
}
}
}
}
72 changes: 66 additions & 6 deletions docs/openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -404,6 +404,26 @@ Prometheus format.



## AccessRule


Rule defining what actions a role can perform.


| Field | Type | Description |
|-------|------|-------------|
| role | string | |
| actions | array | |


## Action


Available actions in the system.




## Attachment


Expand Down Expand Up @@ -447,6 +467,17 @@ Authentication configuration.
| jwk_config | | |


## AuthorizationConfiguration


Authorization configuration.


| Field | Type | Description |
|-------|------|-------------|
| access_rules | array | |


## AuthorizedResponse


Expand Down Expand Up @@ -492,6 +523,7 @@ Global service configuration.
| database | | |
| mcp_servers | array | |
| authentication | | |
| authorization | | |
| customization | | |
| inference | | |

Expand Down Expand Up @@ -533,16 +565,18 @@ Attributes:
created_at: When the conversation was created.
last_message_at: When the last message was sent.
message_count: Number of user messages in the conversation.
model: The model used for the conversation.
last_used_model: The last model used for the conversation.
last_used_provider: The provider of the last used model.

Example:
```python
conversation = ConversationSummary(
conversation = ConversationDetails(
conversation_id="123e4567-e89b-12d3-a456-426614174000"
created_at="2024-01-01T00:00:00Z",
last_message_at="2024-01-01T00:05:00Z",
message_count=5,
model="gemini/gemini-2.0-flash"
last_used_model="gemini/gemini-2.0-flash",
last_used_provider="gemini",
)
```

Expand Down Expand Up @@ -607,13 +641,15 @@ Example:
created_at="2024-01-01T00:00:00Z",
last_message_at="2024-01-01T00:05:00Z",
message_count=5,
model="gemini/gemini-2.0-flash"
last_used_model="gemini/gemini-2.0-flash",
last_used_provider="gemini",
),
ConversationDetails(
conversation_id="456e7890-e12b-34d5-a678-901234567890"
created_at="2024-01-01T01:00:00Z",
message_count=2,
model="gemini/gemini-2.5-flash"
last_used_model="gemini/gemini-2.0-flash",
last_used_provider="gemini",
)
]
)
Expand Down Expand Up @@ -773,7 +809,7 @@ Inference configuration.
## InfoResponse


Model representing a response to a info request.
Model representing a response to an info request.

Attributes:
name: Service name.
Expand All @@ -794,6 +830,14 @@ Example:
| version | string | Service version |


## JsonPathOperator


Supported operators for JSONPath evaluation.




## JwkConfiguration


Expand All @@ -816,6 +860,22 @@ JWT configuration.
|-------|------|-------------|
| user_id_claim | string | |
| username_claim | string | |
| role_rules | array | |


## JwtRoleRule


Rule for extracting roles from JWT claims.


| Field | Type | Description |
|-------|------|-------------|
| jsonpath | string | |
| operator | | |
| negate | boolean | |
| value | | |
| roles | array | |


## LivenessResponse
Expand Down
Loading