From a133b77f6cdb1d1fced5a5580db9901ba28d9526 Mon Sep 17 00:00:00 2001 From: Andrej Simurka Date: Thu, 6 Nov 2025 10:32:45 +0100 Subject: [PATCH] Fixed 403 error descriptions in swagger --- docs/openapi.json | 236 +++++++++++++-------------- src/app/endpoints/feedback.py | 4 - src/app/endpoints/query.py | 2 +- src/app/endpoints/query_v2.py | 2 +- src/app/endpoints/streaming_query.py | 2 +- 5 files changed, 113 insertions(+), 133 deletions(-) diff --git a/docs/openapi.json b/docs/openapi.json index 1d32805be..529d9b417 100644 --- a/docs/openapi.json +++ b/docs/openapi.json @@ -324,7 +324,7 @@ "query" ], "summary": "Query Endpoint Handler", - "description": "Handle request to the /query endpoint.\n\nProcesses a POST request to the /query endpoint, forwarding the\nuser's query to a selected Llama Stack LLM or agent and\nreturning the generated response.\n\nValidates configuration and authentication, selects the appropriate model\nand provider, retrieves the LLM response, updates metrics, and optionally\nstores a transcript of the interaction. Handles connection errors to the\nLlama Stack service by returning an HTTP 500 error.\n\nReturns:\n QueryResponse: Contains the conversation ID and the LLM-generated response.", + "description": "Handle request to the /query endpoint using Agent API.\n\nThis is a wrapper around query_endpoint_handler_base that provides\nthe Agent API specific retrieve_response and get_topic_summary functions.\n\nReturns:\n QueryResponse: Contains the conversation ID and the LLM-generated response.", "operationId": "query_endpoint_handler_v1_query_post", "requestBody": { "content": { @@ -366,7 +366,7 @@ } }, "403": { - "description": "User is not authorized", + "description": "Client does not have permission to access conversation", "content": { "application/json": { "schema": { @@ -452,7 +452,7 @@ } }, "403": { - "description": "User is not authorized", + "description": "Client does not have permission to access conversation", "content": { "application/json": { "schema": { @@ -631,7 +631,7 @@ "operationId": "feedback_status_v1_feedback_status_get", "responses": { "200": { - "description": "Successful Response", + "description": "Feedback status successfully retrieved", "content": { "application/json": { "schema": { @@ -661,7 +661,7 @@ }, "responses": { "200": { - "description": "Successful Response", + "description": "Feedback status successfully updated", "content": { "application/json": { "schema": { @@ -670,6 +670,26 @@ } } }, + "401": { + "description": "Missing or invalid credentials provided by client", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + } + } + } + }, + "403": { + "description": "Client does not have permission to access resource", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + } + } + } + }, "422": { "description": "Validation Error", "content": { @@ -1179,6 +1199,83 @@ } } }, + "/v2/query": { + "post": { + "tags": [ + "query_v2" + ], + "summary": "Query Endpoint Handler V2", + "description": "Handle request to the /query endpoint using Responses API.\n\nThis is a wrapper around query_endpoint_handler_base that provides\nthe Responses API specific retrieve_response and get_topic_summary functions.\n\nReturns:\n QueryResponse: Contains the conversation ID and the LLM-generated response.", + "operationId": "query_endpoint_handler_v2_v2_query_post", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryRequest" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryResponse" + } + } + }, + "conversation_id": "123e4567-e89b-12d3-a456-426614174000", + "response": "LLM answer", + "referenced_documents": [ + { + "doc_url": "https://docs.openshift.com/container-platform/4.15/operators/olm/index.html", + "doc_title": "Operator Lifecycle Manager (OLM)" + } + ] + }, + "400": { + "description": "Missing or invalid credentials provided by client", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedResponse" + } + } + } + }, + "403": { + "description": "Client does not have permission to access conversation", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ForbiddenResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "detail": { + "response": "Unable to connect to Llama Stack", + "cause": "Connection error." + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, "/readiness": { "get": { "tags": [ @@ -1436,7 +1533,7 @@ } ] }, - "AuthenticationConfiguration-Input": { + "AuthenticationConfiguration": { "properties": { "module": { "type": "string", @@ -1476,7 +1573,7 @@ "jwk_config": { "anyOf": [ { - "$ref": "#/components/schemas/JwkConfiguration-Input" + "$ref": "#/components/schemas/JwkConfiguration" }, { "type": "null" @@ -1489,75 +1586,7 @@ "title": "AuthenticationConfiguration", "description": "Authentication configuration." }, - "AuthenticationConfiguration-Output": { - "properties": { - "module": { - "type": "string", - "title": "Module", - "default": "noop" - }, - "skip_tls_verification": { - "type": "boolean", - "title": "Skip Tls Verification", - "default": false - }, - "k8s_cluster_api": { - "anyOf": [ - { - "type": "string", - "minLength": 1, - "format": "uri" - }, - { - "type": "null" - } - ], - "title": "K8S Cluster Api" - }, - "k8s_ca_cert_path": { - "anyOf": [ - { - "type": "string", - "format": "file-path" - }, - { - "type": "null" - } - ], - "title": "K8S Ca Cert Path" - }, - "jwk_config": { - "anyOf": [ - { - "$ref": "#/components/schemas/JwkConfiguration-Output" - }, - { - "type": "null" - } - ] - } - }, - "additionalProperties": false, - "type": "object", - "title": "AuthenticationConfiguration", - "description": "Authentication configuration." - }, - "AuthorizationConfiguration-Input": { - "properties": { - "access_rules": { - "items": { - "$ref": "#/components/schemas/AccessRule" - }, - "type": "array", - "title": "Access Rules" - } - }, - "additionalProperties": false, - "type": "object", - "title": "AuthorizationConfiguration", - "description": "Authorization configuration." - }, - "AuthorizationConfiguration-Output": { + "AuthorizationConfiguration": { "properties": { "access_rules": { "items": { @@ -1753,12 +1782,12 @@ "title": "Mcp Servers" }, "authentication": { - "$ref": "#/components/schemas/AuthenticationConfiguration-Output" + "$ref": "#/components/schemas/AuthenticationConfiguration" }, "authorization": { "anyOf": [ { - "$ref": "#/components/schemas/AuthorizationConfiguration-Output" + "$ref": "#/components/schemas/AuthorizationConfiguration" }, { "type": "null" @@ -2717,7 +2746,7 @@ "title": "JsonPathOperator", "description": "Supported operators for JSONPath evaluation." }, - "JwkConfiguration-Input": { + "JwkConfiguration": { "properties": { "url": { "type": "string", @@ -2726,7 +2755,7 @@ "title": "Url" }, "jwt_configuration": { - "$ref": "#/components/schemas/JwtConfiguration-Input" + "$ref": "#/components/schemas/JwtConfiguration" } }, "additionalProperties": false, @@ -2737,52 +2766,7 @@ "title": "JwkConfiguration", "description": "JWK configuration." }, - "JwkConfiguration-Output": { - "properties": { - "url": { - "type": "string", - "minLength": 1, - "format": "uri", - "title": "Url" - }, - "jwt_configuration": { - "$ref": "#/components/schemas/JwtConfiguration-Output" - } - }, - "additionalProperties": false, - "type": "object", - "required": [ - "url" - ], - "title": "JwkConfiguration", - "description": "JWK configuration." - }, - "JwtConfiguration-Input": { - "properties": { - "user_id_claim": { - "type": "string", - "title": "User Id Claim", - "default": "user_id" - }, - "username_claim": { - "type": "string", - "title": "Username Claim", - "default": "username" - }, - "role_rules": { - "items": { - "$ref": "#/components/schemas/JwtRoleRule" - }, - "type": "array", - "title": "Role Rules" - } - }, - "additionalProperties": false, - "type": "object", - "title": "JwtConfiguration", - "description": "JWT configuration." - }, - "JwtConfiguration-Output": { + "JwtConfiguration": { "properties": { "user_id_claim": { "type": "string", diff --git a/src/app/endpoints/feedback.py b/src/app/endpoints/feedback.py index 8b28437fb..915798237 100644 --- a/src/app/endpoints/feedback.py +++ b/src/app/endpoints/feedback.py @@ -54,10 +54,6 @@ "description": "Feedback status successfully updated", "model": FeedbackStatusUpdateResponse, }, - 400: { - "description": "Missing or invalid credentials provided by client", - "model": UnauthorizedResponse, - }, 401: { "description": "Missing or invalid credentials provided by client", "model": UnauthorizedResponse, diff --git a/src/app/endpoints/query.py b/src/app/endpoints/query.py index 22537c930..8040ed7eb 100644 --- a/src/app/endpoints/query.py +++ b/src/app/endpoints/query.py @@ -83,7 +83,7 @@ "model": UnauthorizedResponse, }, 403: { - "description": "User is not authorized", + "description": "Client does not have permission to access conversation", "model": ForbiddenResponse, }, 500: { diff --git a/src/app/endpoints/query_v2.py b/src/app/endpoints/query_v2.py index 0365d9fde..3ebcf4f8d 100644 --- a/src/app/endpoints/query_v2.py +++ b/src/app/endpoints/query_v2.py @@ -56,7 +56,7 @@ "model": UnauthorizedResponse, }, 403: { - "description": "User is not authorized", + "description": "Client does not have permission to access conversation", "model": ForbiddenResponse, }, 500: { diff --git a/src/app/endpoints/streaming_query.py b/src/app/endpoints/streaming_query.py index d4ad3088a..c1d2c0492 100644 --- a/src/app/endpoints/streaming_query.py +++ b/src/app/endpoints/streaming_query.py @@ -101,7 +101,7 @@ "model": UnauthorizedResponse, }, 403: { - "description": "User is not authorized", + "description": "Client does not have permission to access conversation", "model": ForbiddenResponse, }, 500: {