chore(api): annotate simple contract responses

api/controllers/common/fields.py

@@ -2,8 +2,9 @@
 
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, computed_field
+from pydantic import BaseModel, ConfigDict, Field, computed_field
 
+from fields.base import ResponseModel
 from graphon.file import helpers as file_helpers
 from models.model import IconType
 
@@ -19,6 +20,113 @@ class SystemParameters(BaseModel):
     workflow_file_upload_limit: int
 
 
+class SimpleResultResponse(ResponseModel):
+    result: str
+
+
+class SimpleResultMessageResponse(ResponseModel):
+    result: str
+    message: str
+
+
+class SimpleMessageResponse(ResponseModel):
+    message: str
+
+
+class SimpleDataResponse(ResponseModel):
+    data: str
+
+
+class SimpleResultDataResponse(ResponseModel):
+    result: str
+    data: str
+
+
+class SimpleResultStringListResponse(ResponseModel):
+    result: str
+    data: list[str]
+
+
+class SimpleResultOptionalDataResponse(ResponseModel):
+    result: str
+    data: str | None = None
+
+
+class AccessTokenData(ResponseModel):
+    access_token: str
+
+
+class AccessTokenResultResponse(ResponseModel):
+    result: str
+    data: AccessTokenData
+
+
+class VerificationTokenResponse(ResponseModel):
+    is_valid: bool
+    email: str
+    token: str
+
+
+class LoginStatusResponse(ResponseModel):
+    logged_in: bool
+    app_logged_in: bool
+
+
+class AccessModeResponse(ResponseModel):
+    access_mode: str = Field(serialization_alias="accessMode", validation_alias="accessMode")
+
+
+class BooleanResultResponse(ResponseModel):
+    result: bool
+
+
+class SuccessResponse(ResponseModel):
+    success: bool
+
+
+class UsageCheckResponse(ResponseModel):
+    is_using: bool
+
+
+class UsageCountResponse(ResponseModel):
+    is_using: bool
+    count: int
+
+
+class IndexInfoResponse(ResponseModel):
+    welcome: str
+    api_version: str
+    server_version: str
+
+
+class AvatarUrlResponse(ResponseModel):
+    avatar_url: str
+
+
+class TextContentResponse(ResponseModel):
+    content: str
+
+
+class AllowedExtensionsResponse(ResponseModel):
+    allowed_extensions: list[str]
+
+
+class UrlResponse(ResponseModel):
+    url: str
+
+
+class RedirectUrlResponse(ResponseModel):
+    redirect_url: str
+
+
+class ApiBaseUrlResponse(ResponseModel):
+    api_base_url: str
+
+
+class NewAppResponse(ResponseModel):
+    new_app_id: str
+
+
 class Parameters(BaseModel):
     opening_statement: str | None = None
     suggested_questions: list[str]

api/controllers/console/app/app.py

@@ -12,8 +12,9 @@
 from werkzeug.datastructures import MultiDict
 from werkzeug.exceptions import BadRequest
 
+from controllers.common.fields import RedirectUrlResponse, SimpleResultResponse
 from controllers.common.helpers import FileInfo
-from controllers.common.schema import register_enum_models, register_schema_models
+from controllers.common.schema import register_enum_models, register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.wraps import get_app_model
 from controllers.console.workspace.models import LoadBalancingPayload
@@ -413,6 +414,7 @@ class AppExportResponse(ResponseModel):
 
 
 register_enum_models(console_ns, RetrievalMethod, WorkflowExecutionStatus, DatasetPermissionEnum)
+register_response_schema_models(console_ns, RedirectUrlResponse, SimpleResultResponse)
 
 register_schema_models(
     console_ns,
@@ -724,6 +726,7 @@ def get(self, app_model):
 
 @console_ns.route("/apps/<uuid:app_id>/publish-to-creators-platform")
 class AppPublishToCreatorsPlatformApi(Resource):
+    @console_ns.response(200, "Success", console_ns.models[RedirectUrlResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -861,7 +864,11 @@ def get(self, app_model):
     @console_ns.doc(description="Update app tracing configuration")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[AppTracePayload.__name__])
-    @console_ns.response(200, "Trace configuration updated successfully")
+    @console_ns.response(
+        200,
+        "Trace configuration updated successfully",
+        console_ns.models[SimpleResultResponse.__name__],
+    )
     @console_ns.response(403, "Insufficient permissions")
     @setup_required
     @login_required

api/controllers/console/app/completion.py

@@ -7,7 +7,8 @@
 from werkzeug.exceptions import InternalServerError, NotFound
 
 import services
-from controllers.common.schema import register_schema_models
+from controllers.common.fields import SimpleResultResponse
+from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import (
     AppUnavailableError,
@@ -66,6 +67,7 @@ def validate_uuid(cls, value: str | None) -> str | None:
 
 
 register_schema_models(console_ns, CompletionMessagePayload, ChatMessagePayload)
+register_response_schema_models(console_ns, SimpleResultResponse)
 
 
 # define completion message api for user
@@ -124,7 +126,7 @@ class CompletionMessageStopApi(Resource):
     @console_ns.doc("stop_completion_message")
     @console_ns.doc(description="Stop a running completion message generation")
     @console_ns.doc(params={"app_id": "Application ID", "task_id": "Task ID to stop"})
-    @console_ns.response(200, "Task stopped successfully")
+    @console_ns.response(200, "Task stopped successfully", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -205,7 +207,7 @@ class ChatMessageStopApi(Resource):
     @console_ns.doc("stop_chat_message")
     @console_ns.doc(description="Stop a running chat message generation")
     @console_ns.doc(params={"app_id": "Application ID", "task_id": "Task ID to stop"})
-    @console_ns.response(200, "Task stopped successfully")
+    @console_ns.response(200, "Task stopped successfully", console_ns.models[SimpleResultResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/app/message.py

@@ -9,7 +9,8 @@
 from werkzeug.exceptions import InternalServerError, NotFound
 
 from controllers.common.controller_schemas import MessageFeedbackPayload as _MessageFeedbackPayloadBase
-from controllers.common.schema import register_schema_models
+from controllers.common.fields import SimpleResultResponse
+from controllers.common.schema import register_response_schema_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import (
     CompletionRequestError,
@@ -162,6 +163,7 @@ class MessageInfiniteScrollPaginationResponse(ResponseModel):
     MessageDetailResponse,
     MessageInfiniteScrollPaginationResponse,
 )
+register_response_schema_models(console_ns, SimpleResultResponse)
 
 
 @console_ns.route("/apps/<uuid:app_id>/chat-messages")
@@ -247,7 +249,7 @@ class MessageFeedbackApi(Resource):
     @console_ns.doc(description="Create or update message feedback (like/dislike)")
     @console_ns.doc(params={"app_id": "Application ID"})
     @console_ns.expect(console_ns.models[MessageFeedbackPayload.__name__])
-    @console_ns.response(200, "Feedback updated successfully")
+    @console_ns.response(200, "Feedback updated successfully", console_ns.models[SimpleResultResponse.__name__])
     @console_ns.response(404, "Message not found")
     @console_ns.response(403, "Insufficient permissions")
     @get_app_model

api/controllers/console/app/workflow.py

@@ -12,6 +12,7 @@
 
 import services
 from controllers.common.controller_schemas import DefaultBlockConfigQuery, WorkflowListQuery, WorkflowUpdatePayload
+from controllers.common.fields import NewAppResponse, SimpleResultResponse
 from controllers.common.schema import (
     register_response_schema_model,
     register_response_schema_models,
@@ -290,6 +291,8 @@ class DraftWorkflowTriggerRunAllPayload(BaseModel):
     WorkflowOnlineUser,
     WorkflowOnlineUsersByApp,
     WorkflowOnlineUsersResponse,
+    NewAppResponse,
+    SimpleResultResponse,
 )
 
 
@@ -869,7 +872,7 @@ class WorkflowTaskStopApi(Resource):
     @console_ns.doc("stop_workflow_task")
     @console_ns.doc(description="Stop running workflow task")
     @console_ns.doc(params={"app_id": "Application ID", "task_id": "Task ID"})
-    @console_ns.response(200, "Task stopped successfully")
+    @console_ns.response(200, "Task stopped successfully", console_ns.models[SimpleResultResponse.__name__])
     @console_ns.response(404, "Task not found")
     @console_ns.response(403, "Permission denied")
     @setup_required
@@ -1069,7 +1072,11 @@ class ConvertToWorkflowApi(Resource):
     @console_ns.doc("convert_to_workflow")
     @console_ns.doc(description="Convert application to workflow mode")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Application converted to workflow successfully")
+    @console_ns.response(
+        200,
+        "Application converted to workflow successfully",
+        console_ns.models[NewAppResponse.__name__],
+    )
     @console_ns.response(400, "Application cannot be converted")
     @console_ns.response(403, "Permission denied")
     @setup_required
@@ -1106,7 +1113,11 @@ class WorkflowFeaturesApi(Resource):
     @console_ns.doc("update_workflow_features")
     @console_ns.doc(description="Update draft workflow features")
     @console_ns.doc(params={"app_id": "Application ID"})
-    @console_ns.response(200, "Workflow features updated successfully")
+    @console_ns.response(
+        200,
+        "Workflow features updated successfully",
+        console_ns.models[SimpleResultResponse.__name__],
+    )
     @setup_required
     @login_required
     @account_initialization_required

api/controllers/console/auth/activate.py

@@ -1,5 +1,3 @@
-from typing import Any
-
 from flask import request
 from flask_restx import Resource
 from pydantic import BaseModel, Field, field_validator
@@ -40,16 +38,29 @@ def validate_tz(cls, value: str) -> str:
         return timezone(value)
 
 
-class ActivationCheckResponse(BaseModel):
-    is_valid: bool = Field(description="Whether token is valid")
-    data: dict[str, Any] | None = Field(default=None, description="Activation data if valid")
-
-
 class ActivationResponse(BaseModel):
     result: str = Field(description="Operation result")
 
 
-register_schema_models(console_ns, ActivateCheckQuery, ActivatePayload, ActivationCheckResponse, ActivationResponse)
+class ActivationCheckData(BaseModel):
+    workspace_name: str | None = None
+    workspace_id: str | None = None
+    email: str | None = None
+
+
+class ActivationCheckResponse(BaseModel):
+    is_valid: bool = Field(description="Whether token is valid")
+    data: ActivationCheckData | None = Field(default=None, description="Activation data if valid")
+
+
+register_schema_models(
+    console_ns,
+    ActivateCheckQuery,
+    ActivatePayload,
+    ActivationCheckData,
+    ActivationCheckResponse,
+    ActivationResponse,
+)
 
 
 @console_ns.route("/activate/check")

api/controllers/console/auth/data_source_bearer_auth.py

@@ -1,7 +1,8 @@
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import register_response_schema_models, register_schema_models
+from fields.base import ResponseModel
 from libs.login import current_account_with_tenant, login_required
 from services.auth.api_key_auth_service import ApiKeyAuthService
 
@@ -16,11 +17,26 @@ class ApiKeyAuthBindingPayload(BaseModel):
     credentials: dict = Field(...)
 
 
+class ApiKeyAuthDataSourceItem(ResponseModel):
+    id: str
+    category: str
+    provider: str
+    disabled: bool
+    created_at: int
+    updated_at: int
+
+
+class ApiKeyAuthDataSourceListResponse(ResponseModel):
+    sources: list[ApiKeyAuthDataSourceItem]
+
+
 register_schema_models(console_ns, ApiKeyAuthBindingPayload)
+register_response_schema_models(console_ns, ApiKeyAuthDataSourceItem, ApiKeyAuthDataSourceListResponse)
 
 
 @console_ns.route("/api-key-auth/data-source")
 class ApiKeyAuthDataSource(Resource):
+    @console_ns.response(200, "Success", console_ns.models[ApiKeyAuthDataSourceListResponse.__name__])
     @setup_required
     @login_required
     @account_initialization_required
@@ -70,6 +86,7 @@ class ApiKeyAuthDataSourceBindingDelete(Resource):
     @login_required
     @account_initialization_required
     @is_admin_or_owner_required
+    @console_ns.response(204, "Binding deleted successfully")
     def delete(self, binding_id):
         # The role of the current user in the table must be admin or owner
         _, current_tenant_id = current_account_with_tenant()