refactor: update API routes and documentation for app and datasets endpoints (#25628)

api/controllers/console/datasets/datasets.py

@@ -1,13 +1,13 @@
 import flask_restx
 from flask import request
 from flask_login import current_user
-from flask_restx import Resource, marshal, marshal_with, reqparse
+from flask_restx import Resource, fields, marshal, marshal_with, reqparse
 from sqlalchemy import select
 from werkzeug.exceptions import Forbidden, NotFound
 
 import services
 from configs import dify_config
-from controllers.console import api
+from controllers.console import api, console_ns
 from controllers.console.apikey import api_key_fields, api_key_list
 from controllers.console.app.error import ProviderNotInitializeError
 from controllers.console.datasets.error import DatasetInUseError, DatasetNameDuplicateError, IndexingEstimateError
@@ -48,7 +48,21 @@ def _validate_description_length(description):
     return description
 
 
+@console_ns.route("/datasets")
 class DatasetListApi(Resource):
+    @api.doc("get_datasets")
+    @api.doc(description="Get list of datasets")
+    @api.doc(
+        params={
+            "page": "Page number (default: 1)",
+            "limit": "Number of items per page (default: 20)",
+            "ids": "Filter by dataset IDs (list)",
+            "keyword": "Search keyword",
+            "tag_ids": "Filter by tag IDs (list)",
+            "include_all": "Include all datasets (default: false)",
+        }
+    )
+    @api.response(200, "Datasets retrieved successfully")
     @setup_required
     @login_required
     @account_initialization_required
@@ -100,6 +114,24 @@ class DatasetListApi(Resource):
         response = {"data": data, "has_more": len(datasets) == limit, "limit": limit, "total": total, "page": page}
         return response, 200
 
+    @api.doc("create_dataset")
+    @api.doc(description="Create a new dataset")
+    @api.expect(
+        api.model(
+            "CreateDatasetRequest",
+            {
+                "name": fields.String(required=True, description="Dataset name (1-40 characters)"),
+                "description": fields.String(description="Dataset description (max 400 characters)"),
+                "indexing_technique": fields.String(description="Indexing technique"),
+                "permission": fields.String(description="Dataset permission"),
+                "provider": fields.String(description="Provider"),
+                "external_knowledge_api_id": fields.String(description="External knowledge API ID"),
+                "external_knowledge_id": fields.String(description="External knowledge ID"),
+            },
+        )
+    )
+    @api.response(201, "Dataset created successfully")
+    @api.response(400, "Invalid request parameters")
     @setup_required
     @login_required
     @account_initialization_required
@@ -172,7 +204,14 @@ class DatasetListApi(Resource):
         return marshal(dataset, dataset_detail_fields), 201
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>")
 class DatasetApi(Resource):
+    @api.doc("get_dataset")
+    @api.doc(description="Get dataset details")
+    @api.doc(params={"dataset_id": "Dataset ID"})
+    @api.response(200, "Dataset retrieved successfully", dataset_detail_fields)
+    @api.response(404, "Dataset not found")
+    @api.response(403, "Permission denied")
     @setup_required
     @login_required
     @account_initialization_required
@@ -215,6 +254,23 @@ class DatasetApi(Resource):
 
         return data, 200
 
+    @api.doc("update_dataset")
+    @api.doc(description="Update dataset details")
+    @api.expect(
+        api.model(
+            "UpdateDatasetRequest",
+            {
+                "name": fields.String(description="Dataset name"),
+                "description": fields.String(description="Dataset description"),
+                "permission": fields.String(description="Dataset permission"),
+                "indexing_technique": fields.String(description="Indexing technique"),
+                "external_retrieval_model": fields.Raw(description="External retrieval model settings"),
+            },
+        )
+    )
+    @api.response(200, "Dataset updated successfully", dataset_detail_fields)
+    @api.response(404, "Dataset not found")
+    @api.response(403, "Permission denied")
     @setup_required
     @login_required
     @account_initialization_required
@@ -344,7 +400,12 @@ class DatasetApi(Resource):
             raise DatasetInUseError()
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/use-check")
 class DatasetUseCheckApi(Resource):
+    @api.doc("check_dataset_use")
+    @api.doc(description="Check if dataset is in use")
+    @api.doc(params={"dataset_id": "Dataset ID"})
+    @api.response(200, "Dataset use status retrieved successfully")
     @setup_required
     @login_required
     @account_initialization_required
@@ -355,7 +416,12 @@ class DatasetUseCheckApi(Resource):
         return {"is_using": dataset_is_using}, 200
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/queries")
 class DatasetQueryApi(Resource):
+    @api.doc("get_dataset_queries")
+    @api.doc(description="Get dataset query history")
+    @api.doc(params={"dataset_id": "Dataset ID"})
+    @api.response(200, "Query history retrieved successfully", dataset_query_detail_fields)
     @setup_required
     @login_required
     @account_initialization_required
@@ -385,7 +451,11 @@ class DatasetQueryApi(Resource):
         return response, 200
 
 
+@console_ns.route("/datasets/indexing-estimate")
 class DatasetIndexingEstimateApi(Resource):
+    @api.doc("estimate_dataset_indexing")
+    @api.doc(description="Estimate dataset indexing cost")
+    @api.response(200, "Indexing estimate calculated successfully")
     @setup_required
     @login_required
     @account_initialization_required
@@ -486,7 +556,12 @@ class DatasetIndexingEstimateApi(Resource):
         return response.model_dump(), 200
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/related-apps")
 class DatasetRelatedAppListApi(Resource):
+    @api.doc("get_dataset_related_apps")
+    @api.doc(description="Get applications related to dataset")
+    @api.doc(params={"dataset_id": "Dataset ID"})
+    @api.response(200, "Related apps retrieved successfully", related_app_list)
     @setup_required
     @login_required
     @account_initialization_required
@@ -513,7 +588,12 @@ class DatasetRelatedAppListApi(Resource):
         return {"data": related_apps, "total": len(related_apps)}, 200
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/indexing-status")
 class DatasetIndexingStatusApi(Resource):
+    @api.doc("get_dataset_indexing_status")
+    @api.doc(description="Get dataset indexing status")
+    @api.doc(params={"dataset_id": "Dataset ID"})
+    @api.response(200, "Indexing status retrieved successfully")
     @setup_required
     @login_required
     @account_initialization_required
@@ -560,11 +640,15 @@ class DatasetIndexingStatusApi(Resource):
         return data, 200
 
 
+@console_ns.route("/datasets/api-keys")
 class DatasetApiKeyApi(Resource):
     max_keys = 10
     token_prefix = "dataset-"
     resource_type = "dataset"
 
+    @api.doc("get_dataset_api_keys")
+    @api.doc(description="Get dataset API keys")
+    @api.response(200, "API keys retrieved successfully", api_key_list)
     @setup_required
     @login_required
     @account_initialization_required
@@ -609,9 +693,14 @@ class DatasetApiKeyApi(Resource):
         return api_token, 200
 
 
+@console_ns.route("/datasets/api-keys/<uuid:api_key_id>")
 class DatasetApiDeleteApi(Resource):
     resource_type = "dataset"
 
+    @api.doc("delete_dataset_api_key")
+    @api.doc(description="Delete dataset API key")
+    @api.doc(params={"api_key_id": "API key ID"})
+    @api.response(204, "API key deleted successfully")
     @setup_required
     @login_required
     @account_initialization_required
@@ -641,7 +730,11 @@ class DatasetApiDeleteApi(Resource):
         return {"result": "success"}, 204
 
 
+@console_ns.route("/datasets/api-base-info")
 class DatasetApiBaseUrlApi(Resource):
+    @api.doc("get_dataset_api_base_info")
+    @api.doc(description="Get dataset API base information")
+    @api.response(200, "API base info retrieved successfully")
     @setup_required
     @login_required
     @account_initialization_required
@@ -649,7 +742,11 @@ class DatasetApiBaseUrlApi(Resource):
         return {"api_base_url": (dify_config.SERVICE_API_URL or request.host_url.rstrip("/")) + "/v1"}
 
 
+@console_ns.route("/datasets/retrieval-setting")
 class DatasetRetrievalSettingApi(Resource):
+    @api.doc("get_dataset_retrieval_setting")
+    @api.doc(description="Get dataset retrieval settings")
+    @api.response(200, "Retrieval settings retrieved successfully")
     @setup_required
     @login_required
     @account_initialization_required
@@ -700,7 +797,12 @@ class DatasetRetrievalSettingApi(Resource):
                 raise ValueError(f"Unsupported vector db type {vector_type}.")
 
 
+@console_ns.route("/datasets/retrieval-setting/<string:vector_type>")
 class DatasetRetrievalSettingMockApi(Resource):
+    @api.doc("get_dataset_retrieval_setting_mock")
+    @api.doc(description="Get mock dataset retrieval settings by vector type")
+    @api.doc(params={"vector_type": "Vector store type"})
+    @api.response(200, "Mock retrieval settings retrieved successfully")
     @setup_required
     @login_required
     @account_initialization_required
@@ -749,7 +851,13 @@ class DatasetRetrievalSettingMockApi(Resource):
                 raise ValueError(f"Unsupported vector db type {vector_type}.")
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/error-docs")
 class DatasetErrorDocs(Resource):
+    @api.doc("get_dataset_error_docs")
+    @api.doc(description="Get dataset error documents")
+    @api.doc(params={"dataset_id": "Dataset ID"})
+    @api.response(200, "Error documents retrieved successfully")
+    @api.response(404, "Dataset not found")
     @setup_required
     @login_required
     @account_initialization_required
@@ -763,7 +871,14 @@ class DatasetErrorDocs(Resource):
         return {"data": [marshal(item, document_status_fields) for item in results], "total": len(results)}, 200
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/permission-part-users")
 class DatasetPermissionUserListApi(Resource):
+    @api.doc("get_dataset_permission_users")
+    @api.doc(description="Get dataset permission user list")
+    @api.doc(params={"dataset_id": "Dataset ID"})
+    @api.response(200, "Permission users retrieved successfully")
+    @api.response(404, "Dataset not found")
+    @api.response(403, "Permission denied")
     @setup_required
     @login_required
     @account_initialization_required
@@ -784,7 +899,13 @@ class DatasetPermissionUserListApi(Resource):
         }, 200
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/auto-disable-logs")
 class DatasetAutoDisableLogApi(Resource):
+    @api.doc("get_dataset_auto_disable_logs")
+    @api.doc(description="Get dataset auto disable logs")
+    @api.doc(params={"dataset_id": "Dataset ID"})
+    @api.response(200, "Auto disable logs retrieved successfully")
+    @api.response(404, "Dataset not found")
     @setup_required
     @login_required
     @account_initialization_required
@@ -794,20 +915,3 @@ class DatasetAutoDisableLogApi(Resource):
         if dataset is None:
             raise NotFound("Dataset not found.")
         return DatasetService.get_dataset_auto_disable_logs(dataset_id_str), 200
-
-
-api.add_resource(DatasetListApi, "/datasets")
-api.add_resource(DatasetApi, "/datasets/<uuid:dataset_id>")
-api.add_resource(DatasetUseCheckApi, "/datasets/<uuid:dataset_id>/use-check")
-api.add_resource(DatasetQueryApi, "/datasets/<uuid:dataset_id>/queries")
-api.add_resource(DatasetErrorDocs, "/datasets/<uuid:dataset_id>/error-docs")
-api.add_resource(DatasetIndexingEstimateApi, "/datasets/indexing-estimate")
-api.add_resource(DatasetRelatedAppListApi, "/datasets/<uuid:dataset_id>/related-apps")
-api.add_resource(DatasetIndexingStatusApi, "/datasets/<uuid:dataset_id>/indexing-status")
-api.add_resource(DatasetApiKeyApi, "/datasets/api-keys")
-api.add_resource(DatasetApiDeleteApi, "/datasets/api-keys/<uuid:api_key_id>")
-api.add_resource(DatasetApiBaseUrlApi, "/datasets/api-base-info")
-api.add_resource(DatasetRetrievalSettingApi, "/datasets/retrieval-setting")
-api.add_resource(DatasetRetrievalSettingMockApi, "/datasets/retrieval-setting/<string:vector_type>")
-api.add_resource(DatasetPermissionUserListApi, "/datasets/<uuid:dataset_id>/permission-part-users")
-api.add_resource(DatasetAutoDisableLogApi, "/datasets/<uuid:dataset_id>/auto-disable-logs")

api/controllers/console/datasets/datasets_document.py

@@ -5,12 +5,12 @@ from typing import Literal, cast
 
 from flask import request
 from flask_login import current_user
-from flask_restx import Resource, marshal, marshal_with, reqparse
+from flask_restx import Resource, fields, marshal, marshal_with, reqparse
 from sqlalchemy import asc, desc, select
 from werkzeug.exceptions import Forbidden, NotFound
 
 import services
-from controllers.console import api
+from controllers.console import api, console_ns
 from controllers.console.app.error import (
     ProviderModelCurrentlyNotSupportError,
     ProviderNotInitializeError,
@@ -98,7 +98,12 @@ class DocumentResource(Resource):
         return documents
 
 
+@console_ns.route("/datasets/process-rule")
 class GetProcessRuleApi(Resource):
+    @api.doc("get_process_rule")
+    @api.doc(description="Get dataset document processing rules")
+    @api.doc(params={"document_id": "Document ID (optional)"})
+    @api.response(200, "Process rules retrieved successfully")
     @setup_required
     @login_required
     @account_initialization_required
@@ -140,7 +145,21 @@ class GetProcessRuleApi(Resource):
         return {"mode": mode, "rules": rules, "limits": limits}
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/documents")
 class DatasetDocumentListApi(Resource):
+    @api.doc("get_dataset_documents")
+    @api.doc(description="Get documents in a dataset")
+    @api.doc(
+        params={
+            "dataset_id": "Dataset ID",
+            "page": "Page number (default: 1)",
+            "limit": "Number of items per page (default: 20)",
+            "keyword": "Search keyword",
+            "sort": "Sort order (default: -created_at)",
+            "fetch": "Fetch full details (default: false)",
+        }
+    )
+    @api.response(200, "Documents retrieved successfully")
     @setup_required
     @login_required
     @account_initialization_required
@@ -324,7 +343,23 @@ class DatasetDocumentListApi(Resource):
         return {"result": "success"}, 204
 
 
+@console_ns.route("/datasets/init")
 class DatasetInitApi(Resource):
+    @api.doc("init_dataset")
+    @api.doc(description="Initialize dataset with documents")
+    @api.expect(
+        api.model(
+            "DatasetInitRequest",
+            {
+                "upload_file_id": fields.String(required=True, description="Upload file ID"),
+                "indexing_technique": fields.String(description="Indexing technique"),
+                "process_rule": fields.Raw(description="Processing rules"),
+                "data_source": fields.Raw(description="Data source configuration"),
+            },
+        )
+    )
+    @api.response(201, "Dataset initialized successfully", dataset_and_document_fields)
+    @api.response(400, "Invalid request parameters")
     @setup_required
     @login_required
     @account_initialization_required
@@ -394,7 +429,14 @@ class DatasetInitApi(Resource):
         return response
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/indexing-estimate")
 class DocumentIndexingEstimateApi(DocumentResource):
+    @api.doc("estimate_document_indexing")
+    @api.doc(description="Estimate document indexing cost")
+    @api.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"})
+    @api.response(200, "Indexing estimate calculated successfully")
+    @api.response(404, "Document not found")
+    @api.response(400, "Document already finished")
     @setup_required
     @login_required
     @account_initialization_required
@@ -593,7 +635,13 @@ class DocumentBatchIndexingStatusApi(DocumentResource):
         return data
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/indexing-status")
 class DocumentIndexingStatusApi(DocumentResource):
+    @api.doc("get_document_indexing_status")
+    @api.doc(description="Get document indexing status")
+    @api.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"})
+    @api.response(200, "Indexing status retrieved successfully")
+    @api.response(404, "Document not found")
     @setup_required
     @login_required
     @account_initialization_required
@@ -635,9 +683,21 @@ class DocumentIndexingStatusApi(DocumentResource):
         return marshal(document_dict, document_status_fields)
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>")
 class DocumentApi(DocumentResource):
     METADATA_CHOICES = {"all", "only", "without"}
 
+    @api.doc("get_document")
+    @api.doc(description="Get document details")
+    @api.doc(
+        params={
+            "dataset_id": "Dataset ID",
+            "document_id": "Document ID",
+            "metadata": "Metadata inclusion (all/only/without)",
+        }
+    )
+    @api.response(200, "Document retrieved successfully")
+    @api.response(404, "Document not found")
     @setup_required
     @login_required
     @account_initialization_required
@@ -746,7 +806,16 @@ class DocumentApi(DocumentResource):
         return {"result": "success"}, 204
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/processing/<string:action>")
 class DocumentProcessingApi(DocumentResource):
+    @api.doc("update_document_processing")
+    @api.doc(description="Update document processing status (pause/resume)")
+    @api.doc(
+        params={"dataset_id": "Dataset ID", "document_id": "Document ID", "action": "Action to perform (pause/resume)"}
+    )
+    @api.response(200, "Processing status updated successfully")
+    @api.response(404, "Document not found")
+    @api.response(400, "Invalid action")
     @setup_required
     @login_required
     @account_initialization_required
@@ -781,7 +850,23 @@ class DocumentProcessingApi(DocumentResource):
         return {"result": "success"}, 200
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/metadata")
 class DocumentMetadataApi(DocumentResource):
+    @api.doc("update_document_metadata")
+    @api.doc(description="Update document metadata")
+    @api.doc(params={"dataset_id": "Dataset ID", "document_id": "Document ID"})
+    @api.expect(
+        api.model(
+            "UpdateDocumentMetadataRequest",
+            {
+                "doc_type": fields.String(description="Document type"),
+                "doc_metadata": fields.Raw(description="Document metadata"),
+            },
+        )
+    )
+    @api.response(200, "Document metadata updated successfully")
+    @api.response(404, "Document not found")
+    @api.response(403, "Permission denied")
     @setup_required
     @login_required
     @account_initialization_required
@@ -1015,26 +1100,3 @@ class WebsiteDocumentSyncApi(DocumentResource):
         DocumentService.sync_website_document(dataset_id, document)
 
         return {"result": "success"}, 200
-
-
-api.add_resource(GetProcessRuleApi, "/datasets/process-rule")
-api.add_resource(DatasetDocumentListApi, "/datasets/<uuid:dataset_id>/documents")
-api.add_resource(DatasetInitApi, "/datasets/init")
-api.add_resource(
-    DocumentIndexingEstimateApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/indexing-estimate"
-)
-api.add_resource(DocumentBatchIndexingEstimateApi, "/datasets/<uuid:dataset_id>/batch/<string:batch>/indexing-estimate")
-api.add_resource(DocumentBatchIndexingStatusApi, "/datasets/<uuid:dataset_id>/batch/<string:batch>/indexing-status")
-api.add_resource(DocumentIndexingStatusApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/indexing-status")
-api.add_resource(DocumentApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>")
-api.add_resource(
-    DocumentProcessingApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/processing/<string:action>"
-)
-api.add_resource(DocumentMetadataApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/metadata")
-api.add_resource(DocumentStatusApi, "/datasets/<uuid:dataset_id>/documents/status/<string:action>/batch")
-api.add_resource(DocumentPauseApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/processing/pause")
-api.add_resource(DocumentRecoverApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/processing/resume")
-api.add_resource(DocumentRetryApi, "/datasets/<uuid:dataset_id>/retry")
-api.add_resource(DocumentRenameApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/rename")
-
-api.add_resource(WebsiteDocumentSyncApi, "/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/website-sync")

api/controllers/console/datasets/external.py

@@ -1,10 +1,10 @@
 from flask import request
 from flask_login import current_user
-from flask_restx import Resource, marshal, reqparse
+from flask_restx import Resource, fields, marshal, reqparse
 from werkzeug.exceptions import Forbidden, InternalServerError, NotFound
 
 import services
-from controllers.console import api
+from controllers.console import api, console_ns
 from controllers.console.datasets.error import DatasetNameDuplicateError
 from controllers.console.wraps import account_initialization_required, setup_required
 from fields.dataset_fields import dataset_detail_fields
@@ -21,7 +21,18 @@ def _validate_name(name):
     return name
 
 
+@console_ns.route("/datasets/external-knowledge-api")
 class ExternalApiTemplateListApi(Resource):
+    @api.doc("get_external_api_templates")
+    @api.doc(description="Get external knowledge API templates")
+    @api.doc(
+        params={
+            "page": "Page number (default: 1)",
+            "limit": "Number of items per page (default: 20)",
+            "keyword": "Search keyword",
+        }
+    )
+    @api.response(200, "External API templates retrieved successfully")
     @setup_required
     @login_required
     @account_initialization_required
@@ -79,7 +90,13 @@ class ExternalApiTemplateListApi(Resource):
         return external_knowledge_api.to_dict(), 201
 
 
+@console_ns.route("/datasets/external-knowledge-api/<uuid:external_knowledge_api_id>")
 class ExternalApiTemplateApi(Resource):
+    @api.doc("get_external_api_template")
+    @api.doc(description="Get external knowledge API template details")
+    @api.doc(params={"external_knowledge_api_id": "External knowledge API ID"})
+    @api.response(200, "External API template retrieved successfully")
+    @api.response(404, "Template not found")
     @setup_required
     @login_required
     @account_initialization_required
@@ -138,7 +155,12 @@ class ExternalApiTemplateApi(Resource):
         return {"result": "success"}, 204
 
 
+@console_ns.route("/datasets/external-knowledge-api/<uuid:external_knowledge_api_id>/use-check")
 class ExternalApiUseCheckApi(Resource):
+    @api.doc("check_external_api_usage")
+    @api.doc(description="Check if external knowledge API is being used")
+    @api.doc(params={"external_knowledge_api_id": "External knowledge API ID"})
+    @api.response(200, "Usage check completed successfully")
     @setup_required
     @login_required
     @account_initialization_required
@@ -151,7 +173,24 @@ class ExternalApiUseCheckApi(Resource):
         return {"is_using": external_knowledge_api_is_using, "count": count}, 200
 
 
+@console_ns.route("/datasets/external")
 class ExternalDatasetCreateApi(Resource):
+    @api.doc("create_external_dataset")
+    @api.doc(description="Create external knowledge dataset")
+    @api.expect(
+        api.model(
+            "CreateExternalDatasetRequest",
+            {
+                "external_knowledge_api_id": fields.String(required=True, description="External knowledge API ID"),
+                "external_knowledge_id": fields.String(required=True, description="External knowledge ID"),
+                "name": fields.String(required=True, description="Dataset name"),
+                "description": fields.String(description="Dataset description"),
+            },
+        )
+    )
+    @api.response(201, "External dataset created successfully", dataset_detail_fields)
+    @api.response(400, "Invalid parameters")
+    @api.response(403, "Permission denied")
     @setup_required
     @login_required
     @account_initialization_required
@@ -191,7 +230,24 @@ class ExternalDatasetCreateApi(Resource):
         return marshal(dataset, dataset_detail_fields), 201
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/external-hit-testing")
 class ExternalKnowledgeHitTestingApi(Resource):
+    @api.doc("test_external_knowledge_retrieval")
+    @api.doc(description="Test external knowledge retrieval for dataset")
+    @api.doc(params={"dataset_id": "Dataset ID"})
+    @api.expect(
+        api.model(
+            "ExternalHitTestingRequest",
+            {
+                "query": fields.String(required=True, description="Query text for testing"),
+                "retrieval_model": fields.Raw(description="Retrieval model configuration"),
+                "external_retrieval_model": fields.Raw(description="External retrieval model configuration"),
+            },
+        )
+    )
+    @api.response(200, "External hit testing completed successfully")
+    @api.response(404, "Dataset not found")
+    @api.response(400, "Invalid parameters")
     @setup_required
     @login_required
     @account_initialization_required
@@ -228,8 +284,22 @@ class ExternalKnowledgeHitTestingApi(Resource):
             raise InternalServerError(str(e))
 
 
+@console_ns.route("/test/retrieval")
 class BedrockRetrievalApi(Resource):
     # this api is only for internal testing
+    @api.doc("bedrock_retrieval_test")
+    @api.doc(description="Bedrock retrieval test (internal use only)")
+    @api.expect(
+        api.model(
+            "BedrockRetrievalTestRequest",
+            {
+                "retrieval_setting": fields.Raw(required=True, description="Retrieval settings"),
+                "query": fields.String(required=True, description="Query text"),
+                "knowledge_id": fields.String(required=True, description="Knowledge ID"),
+            },
+        )
+    )
+    @api.response(200, "Bedrock retrieval test completed")
     def post(self):
         parser = reqparse.RequestParser()
         parser.add_argument("retrieval_setting", nullable=False, required=True, type=dict, location="json")
@@ -247,12 +317,3 @@ class BedrockRetrievalApi(Resource):
             args["retrieval_setting"], args["query"], args["knowledge_id"]
         )
         return result, 200
-
-
-api.add_resource(ExternalKnowledgeHitTestingApi, "/datasets/<uuid:dataset_id>/external-hit-testing")
-api.add_resource(ExternalDatasetCreateApi, "/datasets/external")
-api.add_resource(ExternalApiTemplateListApi, "/datasets/external-knowledge-api")
-api.add_resource(ExternalApiTemplateApi, "/datasets/external-knowledge-api/<uuid:external_knowledge_api_id>")
-api.add_resource(ExternalApiUseCheckApi, "/datasets/external-knowledge-api/<uuid:external_knowledge_api_id>/use-check")
-# this api is only for internal test
-api.add_resource(BedrockRetrievalApi, "/test/retrieval")

api/controllers/console/datasets/hit_testing.py

@@ -1,6 +1,6 @@
-from flask_restx import Resource
+from flask_restx import Resource, fields
 
-from controllers.console import api
+from controllers.console import api, console_ns
 from controllers.console.datasets.hit_testing_base import DatasetsHitTestingBase
 from controllers.console.wraps import (
     account_initialization_required,
@@ -10,7 +10,25 @@ from controllers.console.wraps import (
 from libs.login import login_required
 
 
+@console_ns.route("/datasets/<uuid:dataset_id>/hit-testing")
 class HitTestingApi(Resource, DatasetsHitTestingBase):
+    @api.doc("test_dataset_retrieval")
+    @api.doc(description="Test dataset knowledge retrieval")
+    @api.doc(params={"dataset_id": "Dataset ID"})
+    @api.expect(
+        api.model(
+            "HitTestingRequest",
+            {
+                "query": fields.String(required=True, description="Query text for testing"),
+                "retrieval_model": fields.Raw(description="Retrieval model configuration"),
+                "top_k": fields.Integer(description="Number of top results to return"),
+                "score_threshold": fields.Float(description="Score threshold for filtering results"),
+            },
+        )
+    )
+    @api.response(200, "Hit testing completed successfully")
+    @api.response(404, "Dataset not found")
+    @api.response(400, "Invalid parameters")
     @setup_required
     @login_required
     @account_initialization_required
@@ -23,6 +41,3 @@ class HitTestingApi(Resource, DatasetsHitTestingBase):
         self.hit_testing_args_check(args)
 
         return self.perform_hit_testing(dataset, args)
-
-
-api.add_resource(HitTestingApi, "/datasets/<uuid:dataset_id>/hit-testing")

api/controllers/console/datasets/website.py

@@ -1,13 +1,32 @@
-from flask_restx import Resource, reqparse
+from flask_restx import Resource, fields, reqparse
 
-from controllers.console import api
+from controllers.console import api, console_ns
 from controllers.console.datasets.error import WebsiteCrawlError
 from controllers.console.wraps import account_initialization_required, setup_required
 from libs.login import login_required
 from services.website_service import WebsiteCrawlApiRequest, WebsiteCrawlStatusApiRequest, WebsiteService
 
 
+@console_ns.route("/website/crawl")
 class WebsiteCrawlApi(Resource):
+    @api.doc("crawl_website")
+    @api.doc(description="Crawl website content")
+    @api.expect(
+        api.model(
+            "WebsiteCrawlRequest",
+            {
+                "provider": fields.String(
+                    required=True,
+                    description="Crawl provider (firecrawl/watercrawl/jinareader)",
+                    enum=["firecrawl", "watercrawl", "jinareader"],
+                ),
+                "url": fields.String(required=True, description="URL to crawl"),
+                "options": fields.Raw(required=True, description="Crawl options"),
+            },
+        )
+    )
+    @api.response(200, "Website crawl initiated successfully")
+    @api.response(400, "Invalid crawl parameters")
     @setup_required
     @login_required
     @account_initialization_required
@@ -39,7 +58,14 @@ class WebsiteCrawlApi(Resource):
         return result, 200
 
 
+@console_ns.route("/website/crawl/status/<string:job_id>")
 class WebsiteCrawlStatusApi(Resource):
+    @api.doc("get_crawl_status")
+    @api.doc(description="Get website crawl status")
+    @api.doc(params={"job_id": "Crawl job ID", "provider": "Crawl provider (firecrawl/watercrawl/jinareader)"})
+    @api.response(200, "Crawl status retrieved successfully")
+    @api.response(404, "Crawl job not found")
+    @api.response(400, "Invalid provider")
     @setup_required
     @login_required
     @account_initialization_required
@@ -62,7 +88,3 @@ class WebsiteCrawlStatusApi(Resource):
         except Exception as e:
             raise WebsiteCrawlError(str(e))
         return result, 200
-
-
-api.add_resource(WebsiteCrawlApi, "/website/crawl")
-api.add_resource(WebsiteCrawlStatusApi, "/website/crawl/status/<string:job_id>")