feat: API docs for service api (#24425)

Signed-off-by: -LAN- <laipz8200@outlook.com>

api/fields/annotation_fields.py

@@ -1,4 +1,4 @@
-from flask_restx import fields
+from flask_restx import Api, Namespace, fields
 
 from libs.helper import TimestampField
 
@@ -11,6 +11,12 @@ annotation_fields = {
     # 'account': fields.Nested(simple_account_fields, allow_null=True)
 }
 
+
+def build_annotation_model(api_or_ns: Api | Namespace):
+    """Build the annotation model for the API or Namespace."""
+    return api_or_ns.model("Annotation", annotation_fields)
+
+
 annotation_list_fields = {
     "data": fields.List(fields.Nested(annotation_fields)),
 }

api/fields/conversation_fields.py

@@ -1,4 +1,4 @@
-from flask_restx import fields
+from flask_restx import Api, Namespace, fields
 
 from fields.member_fields import simple_account_fields
 from libs.helper import TimestampField
@@ -45,6 +45,12 @@ message_file_fields = {
     "upload_file_id": fields.String(default=None),
 }
 
+
+def build_message_file_model(api_or_ns: Api | Namespace):
+    """Build the message file fields for the API or Namespace."""
+    return api_or_ns.model("MessageFile", message_file_fields)
+
+
 agent_thought_fields = {
     "id": fields.String,
     "chain_id": fields.String,
@@ -209,3 +215,22 @@ conversation_infinite_scroll_pagination_fields = {
     "has_more": fields.Boolean,
     "data": fields.List(fields.Nested(simple_conversation_fields)),
 }
+
+
+def build_conversation_infinite_scroll_pagination_model(api_or_ns: Api | Namespace):
+    """Build the conversation infinite scroll pagination model for the API or Namespace."""
+    simple_conversation_model = build_simple_conversation_model(api_or_ns)
+
+    copied_fields = conversation_infinite_scroll_pagination_fields.copy()
+    copied_fields["data"] = fields.List(fields.Nested(simple_conversation_model))
+    return api_or_ns.model("ConversationInfiniteScrollPagination", copied_fields)
+
+
+def build_conversation_delete_model(api_or_ns: Api | Namespace):
+    """Build the conversation delete model for the API or Namespace."""
+    return api_or_ns.model("ConversationDelete", conversation_delete_fields)
+
+
+def build_simple_conversation_model(api_or_ns: Api | Namespace):
+    """Build the simple conversation model for the API or Namespace."""
+    return api_or_ns.model("SimpleConversation", simple_conversation_fields)

api/fields/conversation_variable_fields.py

@@ -1,4 +1,4 @@
-from flask_restx import fields
+from flask_restx import Api, Namespace, fields
 
 from libs.helper import TimestampField
 
@@ -27,3 +27,19 @@ conversation_variable_infinite_scroll_pagination_fields = {
     "has_more": fields.Boolean,
     "data": fields.List(fields.Nested(conversation_variable_fields)),
 }
+
+
+def build_conversation_variable_model(api_or_ns: Api | Namespace):
+    """Build the conversation variable model for the API or Namespace."""
+    return api_or_ns.model("ConversationVariable", conversation_variable_fields)
+
+
+def build_conversation_variable_infinite_scroll_pagination_model(api_or_ns: Api | Namespace):
+    """Build the conversation variable infinite scroll pagination model for the API or Namespace."""
+    # Build the nested variable model first
+    conversation_variable_model = build_conversation_variable_model(api_or_ns)
+
+    copied_fields = conversation_variable_infinite_scroll_pagination_fields.copy()
+    copied_fields["data"] = fields.List(fields.Nested(conversation_variable_model))
+
+    return api_or_ns.model("ConversationVariableInfiniteScrollPagination", copied_fields)

api/fields/end_user_fields.py

@@ -1,4 +1,4 @@
-from flask_restx import fields
+from flask_restx import Api, Namespace, fields
 
 simple_end_user_fields = {
     "id": fields.String,
@@ -6,3 +6,7 @@ simple_end_user_fields = {
     "is_anonymous": fields.Boolean,
     "session_id": fields.String,
 }
+
+
+def build_simple_end_user_model(api_or_ns: Api | Namespace):
+    return api_or_ns.model("SimpleEndUser", simple_end_user_fields)

api/fields/file_fields.py

@@ -1,4 +1,4 @@
-from flask_restx import fields
+from flask_restx import Api, Namespace, fields
 
 from libs.helper import TimestampField
 
@@ -11,6 +11,19 @@ upload_config_fields = {
     "workflow_file_upload_limit": fields.Integer,
 }
 
+
+def build_upload_config_model(api_or_ns: Api | Namespace):
+    """Build the upload config model for the API or Namespace.
+
+    Args:
+        api_or_ns: Flask-RestX Api or Namespace instance
+
+    Returns:
+        The registered model
+    """
+    return api_or_ns.model("UploadConfig", upload_config_fields)
+
+
 file_fields = {
     "id": fields.String,
     "name": fields.String,
@@ -22,12 +35,37 @@ file_fields = {
     "preview_url": fields.String,
 }
 
+
+def build_file_model(api_or_ns: Api | Namespace):
+    """Build the file model for the API or Namespace.
+
+    Args:
+        api_or_ns: Flask-RestX Api or Namespace instance
+
+    Returns:
+        The registered model
+    """
+    return api_or_ns.model("File", file_fields)
+
+
 remote_file_info_fields = {
     "file_type": fields.String(attribute="file_type"),
     "file_length": fields.Integer(attribute="file_length"),
 }
 
 
+def build_remote_file_info_model(api_or_ns: Api | Namespace):
+    """Build the remote file info model for the API or Namespace.
+
+    Args:
+        api_or_ns: Flask-RestX Api or Namespace instance
+
+    Returns:
+        The registered model
+    """
+    return api_or_ns.model("RemoteFileInfo", remote_file_info_fields)
+
+
 file_fields_with_signed_url = {
     "id": fields.String,
     "name": fields.String,
@@ -38,3 +76,15 @@ file_fields_with_signed_url = {
     "created_by": fields.String,
     "created_at": TimestampField,
 }
+
+
+def build_file_with_signed_url_model(api_or_ns: Api | Namespace):
+    """Build the file with signed URL model for the API or Namespace.
+
+    Args:
+        api_or_ns: Flask-RestX Api or Namespace instance
+
+    Returns:
+        The registered model
+    """
+    return api_or_ns.model("FileWithSignedUrl", file_fields_with_signed_url)

api/fields/member_fields.py

@@ -1,8 +1,17 @@
-from flask_restx import fields
+from flask_restx import Api, Namespace, fields
 
 from libs.helper import AvatarUrlField, TimestampField
 
-simple_account_fields = {"id": fields.String, "name": fields.String, "email": fields.String}
+simple_account_fields = {
+    "id": fields.String,
+    "name": fields.String,
+    "email": fields.String,
+}
+
+
+def build_simple_account_model(api_or_ns: Api | Namespace):
+    return api_or_ns.model("SimpleAccount", simple_account_fields)
+
 
 account_fields = {
     "id": fields.String,

api/fields/message_fields.py

@@ -1,11 +1,19 @@
-from flask_restx import fields
+from flask_restx import Api, Namespace, fields
 
 from fields.conversation_fields import message_file_fields
 from libs.helper import TimestampField
 
 from .raws import FilesContainedField
 
-feedback_fields = {"rating": fields.String}
+feedback_fields = {
+    "rating": fields.String,
+}
+
+
+def build_feedback_model(api_or_ns: Api | Namespace):
+    """Build the feedback model for the API or Namespace."""
+    return api_or_ns.model("Feedback", feedback_fields)
+
 
 agent_thought_fields = {
     "id": fields.String,
@@ -21,6 +29,12 @@ agent_thought_fields = {
     "files": fields.List(fields.String),
 }
 
+
+def build_agent_thought_model(api_or_ns: Api | Namespace):
+    """Build the agent thought model for the API or Namespace."""
+    return api_or_ns.model("AgentThought", agent_thought_fields)
+
+
 retriever_resource_fields = {
     "id": fields.String,
     "message_id": fields.String,

api/fields/tag_fields.py

@@ -1,3 +1,12 @@
-from flask_restx import fields
+from flask_restx import Api, Namespace, fields
 
-tag_fields = {"id": fields.String, "name": fields.String, "type": fields.String, "binding_count": fields.String}
+dataset_tag_fields = {
+    "id": fields.String,
+    "name": fields.String,
+    "type": fields.String,
+    "binding_count": fields.String,
+}
+
+
+def build_dataset_tag_fields(api_or_ns: Api | Namespace):
+    return api_or_ns.model("DataSetTag", dataset_tag_fields)

api/fields/workflow_app_log_fields.py

@@ -1,8 +1,8 @@
-from flask_restx import fields
+from flask_restx import Api, Namespace, fields
 
-from fields.end_user_fields import simple_end_user_fields
-from fields.member_fields import simple_account_fields
-from fields.workflow_run_fields import workflow_run_for_log_fields
+from fields.end_user_fields import build_simple_end_user_model, simple_end_user_fields
+from fields.member_fields import build_simple_account_model, simple_account_fields
+from fields.workflow_run_fields import build_workflow_run_for_log_model, workflow_run_for_log_fields
 from libs.helper import TimestampField
 
 workflow_app_log_partial_fields = {
@@ -15,6 +15,24 @@ workflow_app_log_partial_fields = {
     "created_at": TimestampField,
 }
 
+
+def build_workflow_app_log_partial_model(api_or_ns: Api | Namespace):
+    """Build the workflow app log partial model for the API or Namespace."""
+    workflow_run_model = build_workflow_run_for_log_model(api_or_ns)
+    simple_account_model = build_simple_account_model(api_or_ns)
+    simple_end_user_model = build_simple_end_user_model(api_or_ns)
+
+    copied_fields = workflow_app_log_partial_fields.copy()
+    copied_fields["workflow_run"] = fields.Nested(workflow_run_model, attribute="workflow_run", allow_null=True)
+    copied_fields["created_by_account"] = fields.Nested(
+        simple_account_model, attribute="created_by_account", allow_null=True
+    )
+    copied_fields["created_by_end_user"] = fields.Nested(
+        simple_end_user_model, attribute="created_by_end_user", allow_null=True
+    )
+    return api_or_ns.model("WorkflowAppLogPartial", copied_fields)
+
+
 workflow_app_log_pagination_fields = {
     "page": fields.Integer,
     "limit": fields.Integer,
@@ -22,3 +40,13 @@ workflow_app_log_pagination_fields = {
     "has_more": fields.Boolean,
     "data": fields.List(fields.Nested(workflow_app_log_partial_fields)),
 }
+
+
+def build_workflow_app_log_pagination_model(api_or_ns: Api | Namespace):
+    """Build the workflow app log pagination model for the API or Namespace."""
+    # Build the nested partial model first
+    workflow_app_log_partial_model = build_workflow_app_log_partial_model(api_or_ns)
+
+    copied_fields = workflow_app_log_pagination_fields.copy()
+    copied_fields["data"] = fields.List(fields.Nested(workflow_app_log_partial_model))
+    return api_or_ns.model("WorkflowAppLogPagination", copied_fields)

api/fields/workflow_run_fields.py

@@ -1,4 +1,4 @@
-from flask_restx import fields
+from flask_restx import Api, Namespace, fields
 
 from fields.end_user_fields import simple_end_user_fields
 from fields.member_fields import simple_account_fields
@@ -17,6 +17,11 @@ workflow_run_for_log_fields = {
     "exceptions_count": fields.Integer,
 }
 
+
+def build_workflow_run_for_log_model(api_or_ns: Api | Namespace):
+    return api_or_ns.model("WorkflowRunForLog", workflow_run_for_log_fields)
+
+
 workflow_run_for_list_fields = {
     "id": fields.String,
     "version": fields.String,