Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

50.2 KB
Raw Blame
"""OpenAPI JSON rendering tests for Flask-RESTX API blueprints."""

import json
from collections.abc import Callable, Iterator
from pathlib import Path

import pytest
from flask import Blueprint, Flask

from tests.unit_tests.conftest import app as app  # noqa: PLC0414


@pytest.fixture(autouse=True)
def _swagger_config(config_overrides) -> None:
    config_overrides(SWAGGER_UI_ENABLED=True)


OpenAPIJSONLoader = Callable[[Blueprint, str, bool], str]


@pytest.fixture(scope="module")
def openapi_json() -> OpenAPIJSONLoader:
    """Render each blueprint/config pair once; tests parse their own JSON objects.

    Loading stays lazy so rendering runs after the per-test config and isolation
    fixtures. Tests that change routes or config must render their own documents.
    """
    documents: dict[tuple[Blueprint, str, bool], str] = {}

    def load(blueprint: Blueprint, route: str, include_all_models: bool) -> str:
        key = (blueprint, route, include_all_models)
        if key not in documents:
            app = Flask(__name__)
            app.config["TESTING"] = True
            if include_all_models:
                app.config["RESTX_INCLUDE_ALL_MODELS"] = True
            app.register_blueprint(blueprint)
            response = app.test_client().get(route)
            assert response.status_code == 200
            documents[key] = response.get_data(as_text=True)
        return documents[key]

    return load


@pytest.fixture(scope="module")
def _exported_spec_directory(tmp_path_factory: pytest.TempPathFactory) -> Path:
    return tmp_path_factory.mktemp("swagger-specs")


@pytest.fixture
def exported_console_json(_exported_spec_directory: Path, _swagger_config: None) -> str:
    """Exercise the exporter once; tests parse independent copies of its output."""
    from dev.generate_swagger_specs import generate_specs

    console_openapi_path = _exported_spec_directory / "console-openapi.json"
    if not console_openapi_path.exists():
        written_paths = generate_specs(_exported_spec_directory)
        assert console_openapi_path in written_paths
    return console_openapi_path.read_text(encoding="utf-8")


USER_PROPERTY_SCHEMA = {
    "description": (
        "End-user identifier, defined by your app and unique within it. Identifies the end user for this request. "
        "See [End User Identity](/api-reference/guides/end-user-identity) for endpoint-specific access rules."
    ),
    "type": "string",
}
GENERIC_FILE_SCHEMA = {"description": "The file to upload.", "format": "binary", "type": "string"}
DOCUMENT_CREATE_DATA_SCHEMA = {
    "description": (
        "JSON string containing configuration. Accepts the same fields as "
        "[Create Document by Text](/api-reference/documents/create-document-by-text) (`indexing_technique`, "
        "`doc_form`, `doc_language`, `process_rule`, `retrieval_model`, `embedding_model`, "
        "`embedding_model_provider`) except `name` and `text`."
    ),
    "type": "string",
}
DOCUMENT_UPDATE_DATA_SCHEMA = {
    "description": (
        "JSON string containing document update settings such as `doc_form`, `doc_language`, `process_rule`, "
        "`retrieval_model`, `embedding_model`, and `embedding_model_provider`. `name` and `text` are not used "
        "for file updates."
    ),
    "type": "string",
}


def _schema_refs(value: object) -> set[str]:
    refs: set[str] = set()
    if isinstance(value, dict):
        ref = value.get("$ref")
        if isinstance(ref, str) and ref.startswith("#/components/schemas/"):
            refs.add(ref.removeprefix("#/components/schemas/"))
        for item in value.values():
            refs.update(_schema_refs(item))
    elif isinstance(value, list):
        for item in value:
            refs.update(_schema_refs(item))
    return refs


def _parameters_by_name(operation: dict[str, object]) -> dict[str, dict[str, object]]:
    parameters = operation.get("parameters", [])
    assert isinstance(parameters, list)
    result: dict[str, dict[str, object]] = {}
    for parameter in parameters:
        if not isinstance(parameter, dict):
            continue
        name = parameter.get("name")
        if isinstance(name, str):
            result[name] = parameter
    return result


def _get_operations(payload: dict[str, object]) -> Iterator[tuple[str, dict[str, object]]]:
    paths = payload["paths"]
    assert isinstance(paths, dict)
    for path, path_item in paths.items():
        if not isinstance(path, str) or not isinstance(path_item, dict):
            continue
        operation = path_item.get("get")
        if isinstance(operation, dict):
            yield path, operation


def _multipart_form_schema(operation: dict[str, object]) -> dict[str, object]:
    request_body = operation.get("requestBody")
    assert isinstance(request_body, dict)
    content = request_body.get("content")
    assert isinstance(content, dict)
    multipart = content.get("multipart/form-data")
    assert isinstance(multipart, dict)
    schema = multipart.get("schema")
    assert isinstance(schema, dict)
    return schema


def _json_body_schema(payload: dict[str, object], operation: dict[str, object]) -> dict[str, object]:
    request_body = operation.get("requestBody")
    assert isinstance(request_body, dict)
    content = request_body.get("content")
    assert isinstance(content, dict)
    json_media = content.get("application/json")
    assert isinstance(json_media, dict)
    schema = json_media.get("schema")
    assert isinstance(schema, dict)

    ref = schema.get("$ref")
    if isinstance(ref, str):
        schema_name = ref.removeprefix("#/components/schemas/")
        resolved = payload["components"]["schemas"][schema_name]
        assert isinstance(resolved, dict)
        return resolved

    return schema


def _response_content_types(operation: dict[str, object], status_code: str = "200") -> set[str]:
    responses = operation.get("responses")
    assert isinstance(responses, dict)
    response = responses.get(status_code)
    assert isinstance(response, dict)
    content = response.get("content")
    assert isinstance(content, dict)
    return set(content)


@pytest.mark.parametrize(
    ("first_kwargs", "second_kwargs"),
    [
        ({"min_items": 1}, {"min_items": 2}),
        ({"max_items": 1}, {"max_items": 2}),
        ({"unique": True}, {"unique": False}),
    ],
)
def test_inline_model_name_includes_list_constraints(
    first_kwargs: dict[str, object],
    second_kwargs: dict[str, object],
):
    from flask_restx import fields

    from libs.flask_restx_compat import _inline_model_name

    first_inline_model: dict[object, object] = {"items": fields.List(fields.String, **first_kwargs)}
    second_inline_model: dict[object, object] = {"items": fields.List(fields.String, **second_kwargs)}

    assert _inline_model_name(first_inline_model) != _inline_model_name(second_inline_model)


def test_uuid_path_format_is_derived_from_route_converter():
    from flask_restx import swagger as restx_swagger

    from libs.flask_restx_compat import install_swagger_compatibility

    app = Flask(__name__)
    with app.app_context():
        install_swagger_compatibility()
        params = restx_swagger.extract_path_params("/resources/<uuid:custom_resource_uuid>")

    assert params["custom_resource_uuid"] == {
        "format": "uuid",
        "in": "path",
        "name": "custom_resource_uuid",
        "required": True,
        "type": "string",
    }


def test_openapi_json_endpoints_render():
    from controllers.console import bp as console_bp
    from controllers.service_api import bp as service_api_bp
    from controllers.web import bp as web_bp

    app = Flask(__name__)
    app.config["TESTING"] = True
    app.config["RESTX_INCLUDE_ALL_MODELS"] = True
    app.register_blueprint(console_bp)
    app.register_blueprint(web_bp)
    app.register_blueprint(service_api_bp)

    client = app.test_client()

    for route in ("/console/api/openapi.json", "/api/openapi.json", "/v1/openapi.json"):
        response = client.get(route)

        assert response.status_code == 200
        payload = response.get_json()
        assert payload["openapi"] == "3.1.0"
        assert "paths" in payload
        assert "schemas" in payload["components"]
        assert isinstance(payload["components"]["schemas"], dict)
        if route == "/console/api/openapi.json":
            assert "/test/retrieval" not in payload["paths"]
        missing_refs = _schema_refs(payload) - set(payload["components"]["schemas"])
        assert not missing_refs
        get_request_body_paths = [path for path, operation in _get_operations(payload) if "requestBody" in operation]
        assert not get_request_body_paths

    assert app.config["RESTX_INCLUDE_ALL_MODELS"] is True


def test_console_node_data_migration_documents_canonical_delivery_method_union(
    openapi_json: OpenAPIJSONLoader,
) -> None:
    from controllers.console import bp as console_bp

    payload = json.loads(openapi_json(console_bp, "/console/api/openapi.json", True))
    schemas = payload["components"]["schemas"]
    operation = payload["paths"]["/workspaces/current/human-input/v2/node-data-migration"]["post"]
    request_schema = operation["requestBody"]["content"]["application/json"]["schema"]

    assert request_schema == {"$ref": "#/components/schemas/NodeDataMigrationPayload"}
    payload_schema = schemas["NodeDataMigrationPayload"]
    node_input_ref = payload_schema["properties"]["nodes"]["items"]["$ref"]
    node_input_schema = schemas[node_input_ref.removeprefix("#/components/schemas/")]
    node_data_ref = node_input_schema["properties"]["node_data"]["$ref"]
    node_data_schema = schemas[node_data_ref.removeprefix("#/components/schemas/")]
    method_items = node_data_schema["properties"]["delivery_methods"]["items"]

    assert set(method_items["discriminator"]["mapping"]) == {"webapp", "email", "im"}
    input_ref = node_data_schema["properties"]["inputs"]["items"]["$ref"]
    input_schema = schemas[input_ref.removeprefix("#/components/schemas/")]
    input_variants = input_schema["discriminator"]["mapping"]
    assert set(input_variants) == {"paragraph", "select", "file", "file-list"}
    action_ref = node_data_schema["properties"]["user_actions"]["items"]["$ref"]
    action_schema = schemas[action_ref.removeprefix("#/components/schemas/")]
    assert action_schema["properties"]["title"]["maxLength"] == 100


def test_agent_tts_routes_document_voice_queries_and_binary_audio(openapi_json: OpenAPIJSONLoader):
    from controllers.console import bp as console_bp
    from core.base.tts.audio_mime import SUPPORTED_TTS_AUDIO_MIME_TYPES

    payload = json.loads(openapi_json(console_bp, "/console/api/openapi.json", False))

    voices = payload["paths"]["/agent/{agent_id}/text-to-audio/voices"]["get"]
    language = _parameters_by_name(voices)["language"]
    assert language["in"] == "query"
    assert language["required"] is True
    assert "requestBody" not in voices

    preview = payload["paths"]["/agent/{agent_id}/text-to-audio"]["post"]
    required_fields = _json_body_schema(payload, preview)["required"]
    assert isinstance(required_fields, list)
    assert "text" in required_fields
    assert _response_content_types(preview) == set(SUPPORTED_TTS_AUDIO_MIME_TYPES)
    for media in preview["responses"]["200"]["content"].values():
        assert media["schema"] == {"type": "string", "format": "binary"}
    for status in ("400", "403", "404"):
        assert _response_content_types(preview, status) == {"application/json"}


def test_workflow_config_contracts_describe_node_defaults_and_unpublished_pipelines(
    openapi_json: OpenAPIJSONLoader,
) -> None:
    from controllers.console import bp as console_bp

    payload = json.loads(openapi_json(console_bp, "/console/api/openapi.json", False))
    schemas = payload["components"]["schemas"]
    for resource in ("apps/{app_id}", "rag/pipelines/{pipeline_id}", "snippets/{snippet_id}"):
        operation = payload["paths"][f"/{resource}/workflows/default-workflow-block-configs"]["get"]
        assert operation["responses"]["200"]["content"]["application/json"]["schema"] == {
            "$ref": "#/components/schemas/DefaultBlockConfigsResponse"
        }
    assert schemas["DefaultBlockConfigsResponse"]["items"] == {
        "$ref": "#/components/schemas/DefaultBlockConfigItemResponse"
    }
    item = schemas["DefaultBlockConfigItemResponse"]
    assert set(item["required"]) == {"type", "config"}
    assert item["properties"]["type"]["type"] == "string"
    assert item["properties"]["config"]["type"] == "object"

    published = payload["paths"]["/rag/pipelines/{pipeline_id}/workflows/publish"]["get"]
    assert published["responses"]["200"]["content"]["application/json"]["schema"] == {
        "$ref": "#/components/schemas/RagPipelinePublishedWorkflowResponse"
    }
    assert schemas["RagPipelinePublishedWorkflowResponse"]["anyOf"] == [
        {"$ref": "#/components/schemas/WorkflowResponse"},
        {"type": "null"},
    ]


def test_console_segment_mutation_contracts_survive_admission(openapi_json: OpenAPIJSONLoader) -> None:
    from controllers.console import bp as console_bp

    payload = json.loads(openapi_json(console_bp, "/console/api/openapi.json", False))
    paths = payload["paths"]
    document_path = "/datasets/{dataset_id}/documents/{document_id}"
    mutations = (
        (f"{document_path}/segment", "post", "SegmentCreatePayload", "SegmentDetailResponse"),
        (f"{document_path}/segments/{{segment_id}}", "patch", "SegmentUpdatePayload", "SegmentDetailResponse"),
        (
            f"{document_path}/segments/{{segment_id}}/child_chunks",
            "patch",
            "ChildChunkBatchUpdatePayload",
            "ChildChunkBatchUpdateResponse",
        ),
    )
    for path, method, request_schema, response_schema in mutations:
        operation = paths[path][method]
        assert operation["requestBody"]["content"]["application/json"]["schema"] == {
            "$ref": f"#/components/schemas/{request_schema}"
        }
        assert operation["responses"]["200"]["content"]["application/json"]["schema"] == {
            "$ref": f"#/components/schemas/{response_schema}"
        }

    delete_operation = paths[f"{document_path}/segments"]["delete"]
    assert {status for status in delete_operation["responses"] if status.startswith("2")} == {"204"}
    parameters = _parameters_by_name(delete_operation)
    assert parameters["segment_id"]["in"] == "query"
    assert parameters["segment_id"]["schema"]["type"] == "array"


def test_service_document_file_routes_document_multipart_form_data(openapi_json: OpenAPIJSONLoader):
    from controllers.service_api import bp as service_api_bp

    payload = json.loads(openapi_json(service_api_bp, "/v1/openapi.json", True))
    paths = payload["paths"]

    create_operation = paths["/datasets/{dataset_id}/document/create-by-file"]["post"]
    create_schema = _multipart_form_schema(create_operation)
    create_properties = create_schema["properties"]
    assert isinstance(create_properties, dict)
    assert create_properties["file"] == {
        "description": "Document file to upload.",
        "format": "binary",
        "type": "string",
    }
    assert create_properties["data"] == DOCUMENT_CREATE_DATA_SCHEMA
    assert create_schema["required"] == ["file"]
    assert create_operation["requestBody"]["required"] is True

    for path in (
        "/datasets/{dataset_id}/documents/{document_id}",
        "/datasets/{dataset_id}/documents/{document_id}/update-by-file",
    ):
        update_operation = paths[path]["patch" if path.endswith("{document_id}") else "post"]
        update_schema = _multipart_form_schema(update_operation)
        update_properties = update_schema["properties"]
        assert isinstance(update_properties, dict)
        assert update_properties["file"] == {
            "description": "Replacement document file to upload.",
            "format": "binary",
            "type": "string",
        }
        assert update_properties["data"] == DOCUMENT_UPDATE_DATA_SCHEMA
        assert "required" not in update_schema
        assert update_operation["requestBody"]["required"] is False


def test_service_openapi_merges_public_api_reference_descriptions(openapi_json: OpenAPIJSONLoader):
    from controllers.service_api import bp as service_api_bp

    payload = json.loads(openapi_json(service_api_bp, "/v1/openapi.json", True))

    chat_operation = payload["paths"]["/chat-messages"]["post"]
    assert chat_operation["summary"] == "Send Chat Message"
    assert chat_operation["description"] == "Send a request to the chat application."
    assert chat_operation["tags"] == ["Chatflows", "Chats"]
    assert chat_operation["responses"]["200"]["description"].startswith("Successful response.")

    rename_operation = payload["paths"]["/conversations/{conversation_id}/name"]["post"]
    assert rename_operation["summary"] == "Rename Conversation"
    assert rename_operation["tags"] == ["Conversations"]
    assert _parameters_by_name(rename_operation)["conversation_id"]["description"] == "Conversation ID."


def test_service_document_list_documents_query_params_render(openapi_json: OpenAPIJSONLoader):
    from controllers.service_api import bp as service_api_bp

    payload = json.loads(openapi_json(service_api_bp, "/v1/openapi.json", True))
    operation = payload["paths"]["/datasets/{dataset_id}/documents"]["get"]
    params = _parameters_by_name(operation)

    for name in ("page", "limit", "keyword", "status"):
        assert params[name]["in"] == "query"


def test_service_openapi_documents_decorator_user_contracts(openapi_json: OpenAPIJSONLoader):
    from controllers.service_api import bp as service_api_bp

    payload = json.loads(openapi_json(service_api_bp, "/v1/openapi.json", True))
    paths = payload["paths"]

    required_json_user_operations = (
        ("/completion-messages", "post"),
        ("/chat-messages", "post"),
        ("/messages/{message_id}/feedbacks", "post"),
        ("/form/human_input/{form_token}", "post"),
        ("/workflows/run", "post"),
        ("/workflows/{workflow_id}/run", "post"),
    )
    for path, method in required_json_user_operations:
        schema = _json_body_schema(payload, paths[path][method])
        assert schema["properties"]["user"] == USER_PROPERTY_SCHEMA
        assert "user" in schema["required"]

    for path in ("/chat-messages", "/workflows/run", "/workflows/{workflow_id}/run"):
        rate_limit_description = paths[path]["post"]["responses"]["429"]["description"]
        assert "upstream model provider rate limit" not in rate_limit_description
        assert "too_many_requests" in rate_limit_description
        assert "Dify Cloud workflow execution quota" in rate_limit_description

    task_stop_user_descriptions = {
        "/completion-messages/{task_id}/stop": "Send the same",
        "/chat-messages/{task_id}/stop": "Send the same",
        "/workflows/tasks/{task_id}/stop": "does not need to match",
    }
    for path, expected_behavior in task_stop_user_descriptions.items():
        schema = _json_body_schema(payload, paths[path]["post"])
        assert expected_behavior in schema["properties"]["user"]["description"]
        assert "user" in schema["required"]
        assert "404" not in paths[path]["post"]["responses"]

    optional_json_user_operations = (
        ("/text-to-audio", "post"),
        ("/conversations/{conversation_id}", "delete"),
        ("/conversations/{conversation_id}/name", "post"),
        ("/conversations/{conversation_id}/variables/{variable_id}", "put"),
    )
    for path, method in optional_json_user_operations:
        schema = _json_body_schema(payload, paths[path][method])
        assert schema["properties"]["user"] == USER_PROPERTY_SCHEMA
        assert "user" not in schema.get("required", [])

    messages_params = _parameters_by_name(paths["/messages"]["get"])
    assert messages_params["user"]["in"] == "query"
    assert messages_params["user"]["required"] is False

    events_params = _parameters_by_name(paths["/workflow/{workflow_run_id}/events"]["get"])
    assert events_params["user"]["in"] == "query"
    assert events_params["user"]["required"] is True


def test_service_openapi_documents_app_multipart_contracts(openapi_json: OpenAPIJSONLoader):
    from controllers.service_api import bp as service_api_bp

    payload = json.loads(openapi_json(service_api_bp, "/v1/openapi.json", True))
    paths = payload["paths"]

    for path in ("/files/upload", "/audio-to-text"):
        schema = _multipart_form_schema(paths[path]["post"])
        if path == "/audio-to-text":
            assert schema["properties"]["file"] == {
                "description": (
                    "Audio file to transcribe. Supported MIME types: `audio/mp3`, `audio/mpga`, `audio/m4a`, "
                    "`audio/x-m4a`, `audio/wav`, and `audio/amr`. File size limit is `30 MB`."
                ),
                "format": "binary",
                "type": "string",
            }
        else:
            assert schema["properties"]["file"] == GENERIC_FILE_SCHEMA
        assert schema["properties"]["user"] == USER_PROPERTY_SCHEMA
        assert schema["required"] == ["file"]

    pipeline_schema = _multipart_form_schema(paths["/datasets/pipeline/file-upload"]["post"])
    assert pipeline_schema["properties"]["file"] == GENERIC_FILE_SCHEMA
    assert pipeline_schema["required"] == ["file"]


def test_service_openapi_documents_non_json_response_media_types(openapi_json: OpenAPIJSONLoader):
    from controllers.service_api import bp as service_api_bp

    payload = json.loads(openapi_json(service_api_bp, "/v1/openapi.json", True))
    paths = payload["paths"]

    assert _response_content_types(paths["/chat-messages"]["post"]) == {
        "application/json",
        "text/event-stream",
    }
    assert _response_content_types(paths["/workflow/{workflow_run_id}/events"]["get"]) == {"text/event-stream"}
    assert _response_content_types(paths["/text-to-audio"]["post"]) == {
        "audio/aac",
        "audio/flac",
        "audio/mp4",
        "audio/mpeg",
        "audio/ogg",
        "audio/wav",
        "audio/webm",
    }
    assert _response_content_types(paths["/files/{file_id}/preview"]["get"]) == {"*/*"}
    assert _response_content_types(paths["/datasets/{dataset_id}/documents/download-zip"]["post"]) == {
        "application/zip"
    }


def test_service_openapi_documents_uuid_params_and_deprecated_routes(openapi_json: OpenAPIJSONLoader):
    from controllers.service_api import bp as service_api_bp

    payload = json.loads(openapi_json(service_api_bp, "/v1/openapi.json", True))
    paths = payload["paths"]

    dataset_params = _parameters_by_name(paths["/datasets/{dataset_id}"]["get"])
    assert dataset_params["dataset_id"]["schema"] == {
        "description": "Knowledge base ID.",
        "format": "uuid",
        "type": "string",
    }

    conversation_params = _parameters_by_name(paths["/conversations/{conversation_id}"]["delete"])
    assert conversation_params["conversation_id"]["schema"] == {
        "description": "Conversation ID.",
        "format": "uuid",
        "type": "string",
    }

    compatibility_paths = {
        "/",
        "/datasets/{dataset_id}/document/create_by_file",
        "/datasets/{dataset_id}/document/create_by_text",
        "/datasets/{dataset_id}/documents/{document_id}/update_by_file",
        "/datasets/{dataset_id}/documents/{document_id}/update_by_text",
        "/datasets/{dataset_id}/hit-testing",
    }
    assert compatibility_paths <= set(paths)
    for path in compatibility_paths - {"/"}:
        operation = next(value for key, value in paths[path].items() if key in {"post", "patch"})
        assert operation["deprecated"] is True


def test_service_openapi_documents_path_action_enums(openapi_json: OpenAPIJSONLoader):
    from controllers.service_api import bp as service_api_bp

    payload = json.loads(openapi_json(service_api_bp, "/v1/openapi.json", True))
    paths = payload["paths"]

    annotation_params = _parameters_by_name(paths["/apps/annotation-reply/{action}"]["post"])
    assert annotation_params["action"]["schema"]["enum"] == ["disable", "enable"]

    document_status_params = _parameters_by_name(paths["/datasets/{dataset_id}/documents/status/{action}"]["patch"])
    assert document_status_params["action"]["schema"]["enum"] == ["archive", "disable", "enable", "un_archive"]

    metadata_params = _parameters_by_name(paths["/datasets/{dataset_id}/metadata/built-in/{action}"]["post"])
    assert metadata_params["action"]["schema"]["enum"] == ["disable", "enable"]


def test_service_openapi_documents_conditional_payload_schemas(openapi_json: OpenAPIJSONLoader):
    from controllers.service_api import bp as service_api_bp

    payload = json.loads(openapi_json(service_api_bp, "/v1/openapi.json", True))
    paths = payload["paths"]

    rename_schema = _json_body_schema(payload, paths["/conversations/{conversation_id}/name"]["post"])
    auto_generate_branch, manual_name_branch = rename_schema["anyOf"]
    assert auto_generate_branch["properties"]["auto_generate"]["enum"] == [True]
    assert auto_generate_branch["required"] == ["auto_generate"]
    assert manual_name_branch["properties"]["auto_generate"]["enum"] == [False]
    assert manual_name_branch["properties"]["name"]["pattern"] == r".*\S.*"
    assert manual_name_branch["required"] == ["name"]
    for branch in rename_schema["anyOf"]:
        assert branch["properties"]["user"] == USER_PROPERTY_SCHEMA

    document_update_schema = payload["components"]["schemas"]["DocumentTextUpdate"]
    with_text_branch, without_text_branch = document_update_schema["anyOf"]
    assert with_text_branch["properties"]["text"]["type"] == "string"
    assert with_text_branch["properties"]["name"]["type"] == "string"
    assert "default" not in with_text_branch["properties"]["text"]
    assert "default" not in with_text_branch["properties"]["name"]
    assert with_text_branch["required"] == ["name", "text"]
    assert without_text_branch["properties"]["text"]["type"] == "null"


def test_service_dataset_response_schemas_omit_console_permission_metadata():
    from controllers.console import bp as console_bp
    from controllers.service_api import bp as service_api_bp

    app = Flask(__name__)
    app.config["TESTING"] = True
    app.config["RESTX_INCLUDE_ALL_MODELS"] = True
    app.register_blueprint(console_bp)
    app.register_blueprint(service_api_bp)

    service_payload = app.test_client().get("/v1/openapi.json").get_json()
    service_schemas = service_payload["components"]["schemas"]
    for name in ("DatasetDetailResponse", "DatasetDetailWithPartialMembersResponse"):
        assert "permission_keys" not in service_schemas[name]["properties"]
    assert service_schemas["DatasetListResponse"]["properties"]["data"]["items"] == {
        "$ref": "#/components/schemas/DatasetDetailResponse"
    }

    console_payload = app.test_client().get("/console/api/openapi.json").get_json()
    console_schema = console_payload["components"]["schemas"]["DatasetDetailResponse"]
    assert "permission_keys" in console_schema["properties"]


def test_service_delete_schemas_omit_unenforced_state_constraints(openapi_json: OpenAPIJSONLoader):
    from controllers.service_api import bp as service_api_bp

    paths = json.loads(openapi_json(service_api_bp, "/v1/openapi.json", False))["paths"]

    delete_dataset = paths["/datasets/{dataset_id}"]["delete"]
    assert "409" not in delete_dataset["responses"]
    assert "must not be in use" not in delete_dataset["description"]

    delete_document = paths["/datasets/{dataset_id}/documents/{document_id}"]["delete"]
    assert "document_indexing" not in json.dumps(delete_document["responses"])
    assert "archived_document_immutable" in delete_document["responses"]["403"]["description"]


def test_service_schemas_only_document_reachable_not_found_responses(openapi_json: OpenAPIJSONLoader):
    from controllers.service_api import bp as service_api_bp

    paths = json.loads(openapi_json(service_api_bp, "/v1/openapi.json", False))["paths"]

    for path, method in (
        ("/info", "get"),
        ("/meta", "get"),
        ("/parameters", "get"),
        ("/workflows/run", "post"),
        ("/completion-messages", "post"),
    ):
        assert "404" not in paths[path][method]["responses"]
        assert "400" in paths[path][method]["responses"]

    annotation_status = paths["/apps/annotation-reply/{action}/status/{job_id}"]["get"]["responses"]
    assert "404" in annotation_status
    assert "400" in annotation_status
    assert "404" in paths["/workflows/{workflow_id}/run"]["post"]["responses"]
    assert "404" in paths["/chat-messages"]["post"]["responses"]


@pytest.mark.parametrize(
    ("path", "method", "validates_payload"),
    [
        ("/apps/annotation-reply/{action}", "post", True),
        ("/apps/annotation-reply/{action}/status/{job_id}", "get", False),
        ("/apps/annotations", "get", True),
        ("/apps/annotations", "post", True),
        ("/apps/annotations/{annotation_id}", "put", True),
        ("/apps/annotations/{annotation_id}", "delete", False),
    ],
)
def test_annotation_schemas_document_admission_and_validation_errors(
    openapi_json: OpenAPIJSONLoader, path: str, method: str, validates_payload: bool
) -> None:
    from controllers.service_api import bp as service_api_bp

    payload = json.loads(openapi_json(service_api_bp, "/v1/openapi.json", False))
    responses = payload["paths"][path][method]["responses"]
    schemas = payload["components"]["schemas"]

    assert {"400", "401", "403", "404"} <= responses.keys()
    assert "invalid_param" in responses["400"]["description"]
    assert "missing workspace" not in responses["400"]["description"]
    documented = _schema_refs(responses["403"])
    for name, code in {
        "AppNotFoundError": "app_not_found",
        "AppAbnormalStatusError": "app_abnormal_status",
        "AppApiDisabledError": "app_api_disabled",
        "WorkspaceNotFoundError": "workspace_not_found",
        "WorkspaceArchivedError": "workspace_archived",
        "ForbiddenError": "forbidden",
    }.items():
        assert name in documented
        properties = schemas[name]["allOf"][1]["properties"]
        assert properties["code"]["const"] == code
        assert properties["status"]["const"] == 403
    assert ("422" in responses) == validates_payload
    if validates_payload:
        assert "unprocessable_entity" in responses["422"]["description"]


def test_service_openapi_does_not_encode_docs_coverage_boundaries(openapi_json: OpenAPIJSONLoader):
    from controllers.service_api import bp as service_api_bp

    payload = json.loads(openapi_json(service_api_bp, "/v1/openapi.json", True))
    paths = payload["paths"]

    for path_item in paths.values():
        assert isinstance(path_item, dict)
        for method in ("delete", "get", "patch", "post", "put"):
            operation = path_item.get(method)
            if not isinstance(operation, dict):
                continue
            assert "x-dify-api-reference-visibility" not in operation
            assert "x-dify-api-lifecycle" not in operation

    assert paths["/datasets/{dataset_id}/documents/{document_id}/update-by-file"]["post"]["deprecated"] is True


def test_service_openapi_documents_auth_and_compatibility_payloads(openapi_json: OpenAPIJSONLoader):
    from controllers.service_api import bp as service_api_bp

    payload = json.loads(openapi_json(service_api_bp, "/v1/openapi.json", True))

    assert payload["components"]["securitySchemes"]["Bearer"] == {
        "bearerFormat": "API_KEY",
        "description": "Use the Service API key as a Bearer token in the Authorization header.",
        "scheme": "bearer",
        "type": "http",
    }
    assert payload["paths"]["/"]["get"]["security"] == []

    tag_unbinding_schema = payload["components"]["schemas"]["TagUnbindingPayload"]
    assert tag_unbinding_schema["description"] == (
        "Accepts either the legacy tag_id payload or the normalized tag_ids payload."
    )
    tag_id_schema, tag_ids_schema = tag_unbinding_schema["anyOf"]
    assert tag_id_schema["properties"]["tag_id"]["description"] == ("Legacy single tag ID accepted by the Service API.")
    assert tag_id_schema["required"] == ["tag_id", "target_id"]
    assert tag_ids_schema["properties"]["tag_id"]["anyOf"] == [{"type": "string"}, {"type": "null"}]
    assert "nullable" not in tag_ids_schema["properties"]["tag_id"]
    assert tag_ids_schema["properties"]["tag_ids"]["minItems"] == 1
    assert tag_ids_schema["required"] == ["tag_ids", "target_id"]


def test_console_account_avatar_query_param_renders_as_query(openapi_json: OpenAPIJSONLoader):
    from controllers.console import bp as console_bp

    payload = json.loads(openapi_json(console_bp, "/console/api/openapi.json", True))
    operation = payload["paths"]["/account/avatar"]["get"]
    params = _parameters_by_name(operation)

    assert "payload" not in params
    assert params["avatar"]["in"] == "query"
    assert params["avatar"]["required"] is True


def test_console_account_profile_patch_without_legacy_update_routes(openapi_json: OpenAPIJSONLoader):
    from controllers.console import bp as console_bp

    payload = json.loads(openapi_json(console_bp, "/console/api/openapi.json", True))
    paths = payload["paths"]

    profile_patch = paths["/account/profile"]["patch"]
    assert profile_patch.get("deprecated") is not True
    profile_patch_schema = _json_body_schema(payload, profile_patch)
    assert profile_patch_schema["type"] == "object"
    assert profile_patch_schema["additionalProperties"] is False
    assert "required" not in profile_patch_schema
    assert profile_patch_schema["properties"]["name"]["type"] == "string"

    for path in (
        "/account/name",
        "/account/avatar",
        "/account/interface-language",
        "/account/interface-theme",
        "/account/timezone",
    ):
        assert "post" not in paths.get(path, {})

    assert paths["/account/avatar"]["get"].get("deprecated") is not True


def test_console_agent_debug_conversation_refresh_has_no_body(openapi_json: OpenAPIJSONLoader):
    from controllers.console import bp as console_bp

    payload = json.loads(openapi_json(console_bp, "/console/api/openapi.json", False))
    operation = payload["paths"]["/agent/{agent_id}/debug-conversation/refresh"]["post"]

    assert "requestBody" not in operation
    assert "AgentDebugConversationRefreshPayload" not in payload["components"]["schemas"]


def test_console_member_invite_documents_bad_request_response(openapi_json: OpenAPIJSONLoader):
    from controllers.console import bp as console_bp

    payload = json.loads(openapi_json(console_bp, "/console/api/openapi.json", True))
    operation = payload["paths"]["/workspaces/current/members/invite-email"]["post"]
    response_schema = operation["responses"]["400"]["content"]["application/json"]["schema"]

    # The declared invite body and the operation's documented business errors can all answer 400.
    assert response_schema["anyOf"][0] == {"$ref": "#/components/schemas/MemberInviteErrorResponse"}
    documented = {option["$ref"].rsplit("/", 1)[-1] for option in response_schema["anyOf"][1:]}
    assert {"InvalidRoleError", "LimitExceededError"} <= documented
    assert payload["components"]["schemas"]["InvalidRoleError"]["allOf"][1]["properties"]["code"] == {
        "const": "invalid_role",
        "type": "string",
    }
    assert payload["components"]["schemas"]["MemberInviteErrorResponse"] == {
        "properties": {
            "code": {
                "enum": ["invalid_param", "invalid_role", "limit_exceeded"],
                "title": "Code",
                "type": "string",
            },
            "message": {"title": "Message", "type": "string"},
            "status": {"const": 400, "title": "Status", "type": "integer"},
        },
        "required": ["code", "message", "status"],
        "title": "MemberInviteErrorResponse",
        "type": "object",
    }


def test_console_billing_reason_errors_are_documented(openapi_json: OpenAPIJSONLoader) -> None:
    from controllers.console import bp as console_bp

    payload = json.loads(openapi_json(console_bp, "/console/api/openapi.json", True))
    control_plane = {
        "403": {"NetworkAccessForbiddenError", "NetworkAccessNotEntitledError", "NetworkAccessRoleDeniedError"},
        "502": {"BillingOperationFailedError"},
        "503": {"BillingUnavailableError"},
    }
    expected = {
        ("/compliance/download", "get"): {
            "403": {"ComplianceDownloadForbiddenError"},
            "404": {"ComplianceDocumentNotFoundError"},
            "429": {"BillingRequestInProgressError"},
        },
        ("/account/education/verify", "get"): {
            "400": {"EducationVerifyFailedError"},
            "429": {"BillingRequestInProgressError"},
            "502": {"BillingOperationFailedError"},
            "503": {"BillingUnavailableError"},
        },
        ("/account/education", "post"): {
            "400": {"EducationActivateFailedError"},
            "429": {"BillingRequestInProgressError"},
            "502": {"BillingOperationFailedError"},
            "503": {"BillingUnavailableError"},
        },
        ("/account/education", "get"): {
            "429": {"BillingRequestInProgressError"},
            "502": {"BillingOperationFailedError"},
            "503": {"BillingUnavailableError"},
        },
        ("/workspaces/current/network-access-groups", "get"): control_plane,
        ("/workspaces/current/network-access-groups", "post"): {
            **control_plane,
            "403": {*control_plane["403"], "PaidPlanRequiredError"},
            "400": {"NetworkAccessInvalidInputError"},
            "409": {"NetworkAccessGroupNameConflictError"},
        },
        ("/workspaces/current/network-access-groups/{group_id}", "put"): {
            **control_plane,
            "400": {"NetworkAccessInvalidInputError"},
            "404": {"NetworkAccessGroupNotFoundError"},
            "409": {"NetworkAccessGroupNameConflictError", "NetworkAccessVersionConflictError"},
        },
        ("/workspaces/current/network-access-groups/{group_id}", "delete"): {
            **control_plane,
            "404": {"NetworkAccessGroupNotFoundError"},
            "409": {"NetworkAccessGroupBoundError", "NetworkAccessVersionConflictError"},
        },
        ("/apps/{app_id}/network-access-group", "put"): {
            **control_plane,
            "400": {
                "NetworkAccessInvalidInputError",
                "NetworkAccessUnsupportedAccessPointsError",
                "NetworkAccessUnsupportedAppModeError",
            },
            "404": {"AppNotFoundError", "NetworkAccessGroupNotFoundError"},
            "409": {"NetworkAccessVersionConflictError"},
        },
    }

    for (path, method), responses in expected.items():
        operation = payload["paths"][path][method]
        for status, components in responses.items():
            schema = operation["responses"][status]["content"]["application/json"]["schema"]
            documented = {option["$ref"].rpartition("/")[2] for option in schema["anyOf"]}
            assert components <= documented, (path, method, status)

    expected_codes = {
        "BillingRequestInProgressError": ("billing_request_in_progress", 429),
        "ComplianceDocumentNotFoundError": ("compliance_document_not_found", 404),
        "ComplianceDownloadForbiddenError": ("compliance_download_forbidden", 403),
        "EducationVerifyFailedError": ("education_verify_failed", 400),
        "EducationActivateFailedError": ("education_activate_failed", 400),
        "NetworkAccessInvalidInputError": ("network_access_invalid_input", 400),
        "NetworkAccessForbiddenError": ("network_access_forbidden", 403),
        "NetworkAccessNotEntitledError": ("network_access_not_entitled", 403),
        "NetworkAccessGroupNotFoundError": ("network_access_group_not_found", 404),
        "NetworkAccessVersionConflictError": ("network_access_version_conflict", 409),
        "NetworkAccessGroupNameConflictError": ("network_access_group_name_conflict", 409),
        "NetworkAccessGroupBoundError": ("network_access_group_bound", 409),
        "NetworkAccessRoleDeniedError": ("network_access_role_denied", 403),
        "NetworkAccessUnsupportedAppModeError": ("network_access_unsupported_app_mode", 400),
        "NetworkAccessUnsupportedAccessPointsError": ("network_access_unsupported_access_points", 400),
        "PaidPlanRequiredError": ("paid_plan_required", 403),
    }
    for component, (code, status) in expected_codes.items():
        properties = payload["components"]["schemas"][component]["allOf"][1]["properties"]
        assert properties["code"]["const"] == code
        assert properties["status"]["const"] == status


def test_console_billing_routes_document_error_responses(openapi_json: OpenAPIJSONLoader):
    from controllers.console import bp as console_bp

    payload = json.loads(openapi_json(console_bp, "/console/api/openapi.json", True))
    expected_responses = {
        ("/billing/subscription", "get"): {
            "422": "BillingUnprocessableEntityErrorResponse",
            "502": "BillingOperationFailedErrorResponse",
            "503": "BillingUnavailableErrorResponse",
        },
        ("/billing/invoices", "get"): {
            "502": "BillingOperationFailedErrorResponse",
            "503": "BillingUnavailableErrorResponse",
        },
        ("/compliance/download", "get"): {
            "422": "BillingUnprocessableEntityErrorResponse",
            "429": "ComplianceRateLimitErrorResponse",
            "502": "BillingOperationFailedErrorResponse",
            "503": "BillingUnavailableErrorResponse",
        },
    }

    for (path, method), responses in expected_responses.items():
        operation = payload["paths"][path][method]
        for status, model_name in responses.items():
            schema = operation["responses"][status]["content"]["application/json"]["schema"]
            # The declared model is unioned with the error body the handlers can still send.
            assert schema["anyOf"][0] == {"$ref": f"#/components/schemas/{model_name}"}

        if path.startswith("/billing/"):
            forbidden_response = operation["responses"]["403"]
            assert forbidden_response["description"] == "Forbidden"
            forbidden_schema = forbidden_response["content"]["application/json"]["schema"]
            assert forbidden_schema == {"$ref": "#/components/schemas/ErrorResponse"}

    expected_error_contracts = {
        "BillingUnprocessableEntityErrorResponse": ("unprocessable_entity", 422),
        "ComplianceRateLimitErrorResponse": ("compliance_rate_limit", 429),
        "BillingOperationFailedErrorResponse": ("billing_operation_failed", 502),
        "BillingUnavailableErrorResponse": ("billing_unavailable", 503),
    }
    schemas = payload["components"]["schemas"]
    for model_name, (error_code, status) in expected_error_contracts.items():
        properties = schemas[model_name]["properties"]
        assert properties["code"]["const"] == error_code
        assert properties["status"]["const"] == status

    compliance_response = schemas["ComplianceDownloadResponse"]
    assert set(compliance_response["properties"]) == {"url"}
    assert compliance_response["required"] == ["url"]


def test_console_model_provider_checkout_route_is_deprecated(openapi_json: OpenAPIJSONLoader):
    from controllers.console import bp as console_bp

    payload = json.loads(openapi_json(console_bp, "/console/api/openapi.json", True))
    operation = payload["paths"]["/workspaces/current/model-providers/{provider}/checkout-url"]["get"]

    assert operation["deprecated"] is True


def test_console_plugin_category_list_exported_schema_uses_typed_items(exported_console_json: str):
    payload = json.loads(exported_console_json)
    operation = payload["paths"]["/workspaces/current/plugin/{category}/list"]["get"]
    parameters = {parameter["name"]: parameter for parameter in operation["parameters"]}
    assert parameters["query"]["in"] == "query"
    assert parameters["tags"]["in"] == "query"
    assert parameters["tags"]["schema"]["type"] == "array"
    assert parameters["language"]["in"] == "query"
    response_ref = operation["responses"]["200"]["content"]["application/json"]["schema"]["$ref"].removeprefix(
        "#/components/schemas/"
    )
    schemas = payload["components"]["schemas"]
    response_schema = schemas[response_ref]

    assert response_schema["properties"]["plugins"]["items"]["$ref"] == (
        "#/components/schemas/PluginCategoryInstalledPluginResponse"
    )
    assert response_schema["properties"]["builtin_tools"]["items"]["$ref"] == (
        "#/components/schemas/PluginCategoryBuiltinToolProviderResponse"
    )

    installed_plugin_schema = schemas["PluginCategoryInstalledPluginResponse"]
    for field in (
        "plugin_unique_identifier",
        "source",
        "version",
        "declaration",
        "endpoints_active",
        "endpoints_setups",
    ):
        assert field in installed_plugin_schema["properties"]

    builtin_tool_schema = schemas["PluginCategoryBuiltinToolProviderResponse"]
    for field in ("plugin_unique_identifier", "team_credentials", "type", "tools"):
        assert field in builtin_tool_schema["properties"]


def test_console_installed_plugin_ids_exported_schema_is_lightweight(exported_console_json: str):
    payload = json.loads(exported_console_json)
    operation = payload["paths"]["/workspaces/current/plugin/installed-ids"]["get"]
    parameters = {parameter["name"]: parameter for parameter in operation["parameters"]}
    assert parameters["category"]["in"] == "query"
    assert parameters["category"]["required"] is True
    assert parameters["category"]["schema"]["enum"] == [
        "agent-strategy",
        "datasource",
        "extension",
        "model",
        "tool",
        "trigger",
    ]
    response_ref = operation["responses"]["200"]["content"]["application/json"]["schema"]["$ref"].removeprefix(
        "#/components/schemas/"
    )
    response_schema = payload["components"]["schemas"][response_ref]

    assert response_schema["required"] == ["plugin_ids"]
    assert response_schema["properties"] == {
        "plugin_ids": {
            "items": {"type": "string"},
            "title": "Plugin Ids",
            "type": "array",
        }
    }


def test_console_datasource_catalog_exports_domain_response_schema(exported_console_json: str) -> None:
    payload = json.loads(exported_console_json)
    operation = payload["paths"]["/rag/pipelines/datasource-plugins"]["get"]

    assert operation.get("parameters", []) == []
    assert "requestBody" not in operation
    assert operation["responses"]["200"]["content"]["application/json"]["schema"] == {
        "$ref": "#/components/schemas/RagPipelineDatasourceListResponse"
    }
    schemas = payload["components"]["schemas"]
    assert schemas["RagPipelineDatasourceListResponse"]["type"] == "array"
    assert schemas["RagPipelineDatasourceListResponse"]["items"] == {
        "$ref": "#/components/schemas/RagPipelineDatasourceProviderResponse"
    }
    provider = schemas["RagPipelineDatasourceProviderResponse"]
    assert set(provider["properties"]) == {
        "provider",
        "plugin_unique_identifier",
        "plugin_id",
        "is_authorized",
        "declaration",
    }
    assert provider["properties"]["declaration"] == {"$ref": "#/components/schemas/DatasourceProviderEntityWithPlugin"}
    assert set(schemas["DatasourceParameterType"]["enum"]) == {
        "string",
        "number",
        "boolean",
        "select",
        "secret-input",
        "file",
        "files",
        "system-files",
    }
    assert schemas["DatasourceEntity"]["properties"]["output_schema"]["anyOf"] == [
        {"additionalProperties": True, "type": "object"},
        {"type": "null"},
    ]
    recommended = payload["paths"]["/rag/pipelines/recommended-plugins"]["get"]
    assert recommended["responses"]["200"]["content"]["application/json"]["schema"] == {
        "$ref": "#/components/schemas/RagPipelineRecommendedPluginsResponse"
    }


def test_console_model_provider_summary_exported_schema_is_lightweight(exported_console_json: str):
    payload = json.loads(exported_console_json)
    operation = payload["paths"]["/workspaces/current/model-providers/summary"]["get"]
    assert operation.get("parameters", []) == []

    response_ref = operation["responses"]["200"]["content"]["application/json"]["schema"]["$ref"].removeprefix(
        "#/components/schemas/"
    )
    response_schema = payload["components"]["schemas"][response_ref]
    assert response_schema["required"] == ["data", "plugins"]
    assert response_schema["properties"]["data"]["items"]["$ref"] == (
        "#/components/schemas/ModelProviderSummaryResponse"
    )
    assert response_schema["properties"]["plugins"]["additionalProperties"]["$ref"] == (
        "#/components/schemas/ModelProviderPluginSummaryResponse"
    )

    provider_properties = payload["components"]["schemas"]["ModelProviderSummaryResponse"]["properties"]
    assert set(provider_properties) == {
        "configurate_methods",
        "custom_configuration",
        "description",
        "icon_small",
        "icon_small_dark",
        "is_configured",
        "label",
        "plugin_id",
        "preferred_provider_type",
        "provider",
        "supported_model_types",
        "system_configuration",
    }
    assert "provider_credential_schema" not in provider_properties
    assert "model_credential_schema" not in provider_properties

    custom_configuration_schema = payload["components"]["schemas"]["ModelProviderCustomConfigurationSummaryResponse"]
    custom_configuration_properties = custom_configuration_schema["properties"]
    assert set(custom_configuration_schema["required"]) == {
        "available_credentials",
        "current_credential_usable",
        "has_custom_models",
        "status",
    }
    assert set(custom_configuration_properties) == {
        "available_credentials",
        "current_credential_id",
        "current_credential_name",
        "current_credential_usable",
        "has_custom_models",
        "status",
    }
    assert custom_configuration_properties["available_credentials"]["items"]["$ref"] == (
        "#/components/schemas/CredentialConfiguration"
    )
    assert "has_credentials" not in custom_configuration_properties

    credential_properties = payload["components"]["schemas"]["CredentialConfiguration"]["properties"]
    assert set(credential_properties) == {
        "credential_id",
        "credential_name",
    }
    assert "encrypted_config" not in credential_properties

    plugin_properties = payload["components"]["schemas"]["ModelProviderPluginSummaryResponse"]["properties"]
    assert set(plugin_properties) == {
        "installation_id",
        "plugin_id",
        "plugin_unique_identifier",
        "runtime_type",
        "source",
        "version",
    }