dify/api/controllers/openapi/__init__.py

from typing import override

from flask import Blueprint
from flask_restx import Namespace

from controllers.openapi._catalog import attach_catalog
from controllers.openapi._errors import ErrorBody, OpenApiErrorCode, OpenApiErrorFormatter
from controllers.openapi._upload import describe_multipart_bodies
from libs.device_flow_security import attach_anti_framing
from libs.external_api import ErrorSpec, ExternalApi

bp = Blueprint("openapi", __name__, url_prefix="/openapi/v1")
attach_anti_framing(bp)
attach_catalog(bp)


class _OpenApi(ExternalApi):
    """The surface's document also names the multipart form its file-bearing bodies accept."""

    error_response_model = ErrorBody

    @override
    def finish_document(self, document: dict[str, object]) -> dict[str, object]:
        return super().finish_document(describe_multipart_bodies(document))

    @override
    def error_code_for(self, spec: ErrorSpec) -> str:
        return OpenApiErrorFormatter.code_for(spec["status"], spec["error_code"])

    @override
    def implicit_error_codes(self, status: int) -> set[str]:
        return {OpenApiErrorFormatter.code_for(status, None)}


api = _OpenApi(
    bp,
    version="1.0",
    title="OpenAPI",
    description="User-scoped programmatic API (bearer auth)",
    error_body_formatter=OpenApiErrorFormatter(),
)

openapi_ns = Namespace("openapi", description="User-scoped operations", path="/")

# Register response/query models BEFORE importing controller modules so that
# @openapi_ns.response / @openapi_ns.expect decorators can resolve model names.
from controllers.common.fields import EventStreamResponse, SimpleResultResponse
from controllers.common.schema import register_enum_models, register_response_schema_models, register_schema_models
from controllers.openapi._models import (
    AccountPayload,
    AccountResponse,
    AdvancedChatNodeRunPayload,
    AdvancedChatRunPayload,
    AdvancedChatWebApp,
    AdvancedChatWebAppPatch,
    AgentAppInfo,
    AgentAppInfoPatch,
    AgentServiceApi,
    AgentWebApp,
    AppDescribeInfo,
    AppDescribeQuery,
    AppDescribeResponse,
    AppDslExportQuery,
    AppDslExportResponse,
    AppDslImportPayload,
    AppDslImportResponse,
    AppInfo,
    AppInfoPatch,
    AppListQuery,
    AppListResponse,
    AppListRow,
    AppSettingsInfo,
    ChatAppInfo,
    ChatAppInfoPatch,
    ChatRunPayload,
    ChatWebApp,
    ChatWebAppPatch,
    CheckDependenciesResponse,
    CompletionRunPayload,
    CreateAppPayload,
    CreatedAppResponse,
    CredentialFormField,
    CredentialRef,
    CredentialWriteResponse,
    CustomModelRow,
    DeviceCodeRequest,
    DeviceCodeResponse,
    DeviceFlowErrorResponse,
    DeviceLookupQuery,
    DeviceLookupResponse,
    DeviceMutateRequest,
    DeviceMutateResponse,
    DevicePollRequest,
    DeviceTokenResponse,
    DraftWorkflowRunPayload,
    DslCheckPayload,
    DslCheckResponse,
    DslIssueRow,
    EnvVariableListResponse,
    EnvVariableSetPayload,
    FileUploadPayload,
    FormSubmitResponse,
    HealthResponse,
    Hint,
    HumanInputFormDefinitionResponse,
    KnowledgeBaseListQuery,
    KnowledgeBaseListResponse,
    KnowledgeBaseRow,
    KnowledgeRetrievalFragment,
    LlmModelBlock,
    MarketplacePluginListResponse,
    MarketplacePluginQuery,
    MarketplacePluginRow,
    MemberActionResponse,
    MemberInvitePayload,
    MemberInviteResponse,
    MemberListQuery,
    MemberListResponse,
    MemberResponse,
    MemberRoleUpdatePayload,
    MessageMetadata,
    ModelCredentialCreatePayload,
    ModelCredentialUpdatePayload,
    ModelListQuery,
    ModelListResponse,
    ModelProviderDetailResponse,
    ModelProviderRow,
    ModelRef,
    ModelRow,
    MultipleRetrievalFragment,
    NodeRunPayload,
    NodeTypeDetailResponse,
    NodeTypeListResponse,
    NodeTypeRow,
    OpenApiFormSubmitPayload,
    PermittedExternalAppsListQuery,
    PermittedExternalAppsListResponse,
    PluginDeleteResponse,
    PluginInstallPayload,
    PluginListQuery,
    PluginListResponse,
    PluginProvides,
    PluginRow,
    PluginTaskItem,
    PluginTaskResponse,
    PluginTaskStartResponse,
    ProviderCredentialCreatePayload,
    ProviderCredentialUpdatePayload,
    PublishPayload,
    PublishResponse,
    ReleaseCheckResponse,
    RestoreResponse,
    RevokeResponse,
    RunListQuery,
    RunListResponse,
    ServerVersionResponse,
    ServiceApi,
    ServiceApiPatch,
    SessionListQuery,
    SessionListResponse,
    SessionRow,
    TaskStopResponse,
    ToolCredentialCreatePayload,
    ToolCredentialUpdatePayload,
    ToolListQuery,
    ToolListResponse,
    ToolProviderDetailResponse,
    ToolProviderRow,
    UsageInfo,
    VersionListQuery,
    VersionListResponse,
    WebApp,
    WebAppAccess,
    WebAppAccessPayload,
    WebAppPatch,
    WebAppToken,
    WorkflowRunData,
    WorkflowRunPayload,
    WorkflowWebApp,
    WorkflowWebAppPatch,
    WorkspaceDetailResponse,
    WorkspaceListQuery,
    WorkspaceListResponse,
    WorkspacePayload,
    WorkspaceSummaryResponse,
)
from fields.file_fields import FileResponse
from fields.workflow_run_fields import (
    WorkflowRunDetailResponse,
    WorkflowRunNodeExecutionListResponse,
    WorkflowRunNodeExecutionResponse,
)
from services.entities.dsl_entities import CheckDependenciesResult, Import

register_schema_models(
    openapi_ns,
    AdvancedChatNodeRunPayload,
    AdvancedChatRunPayload,
    AgentAppInfoPatch,
    AppDescribeQuery,
    AppInfoPatch,
    ChatAppInfoPatch,
    ServiceApiPatch,
    AdvancedChatWebAppPatch,
    ChatWebAppPatch,
    WebAppAccessPayload,
    WebAppPatch,
    WorkflowWebAppPatch,
    AppDslImportPayload,
    DslCheckPayload,
    AppDslExportQuery,
    AppListQuery,
    ChatRunPayload,
    CompletionRunPayload,
    CreateAppPayload,
    DeviceCodeRequest,
    DevicePollRequest,
    DeviceLookupQuery,
    DeviceMutateRequest,
    DraftWorkflowRunPayload,
    FileUploadPayload,
    MemberInvitePayload,
    MemberListQuery,
    MemberRoleUpdatePayload,
    NodeRunPayload,
    OpenApiFormSubmitPayload,
    EnvVariableSetPayload,
    MarketplacePluginQuery,
    PermittedExternalAppsListQuery,
    PluginInstallPayload,
    PluginListQuery,
    ModelListQuery,
    KnowledgeBaseListQuery,
    ToolListQuery,
    ProviderCredentialCreatePayload,
    ProviderCredentialUpdatePayload,
    ModelRef,
    ModelCredentialCreatePayload,
    ModelCredentialUpdatePayload,
    ToolCredentialCreatePayload,
    ToolCredentialUpdatePayload,
    PublishPayload,
    RunListQuery,
    SessionListQuery,
    VersionListQuery,
    WorkflowRunPayload,
    WorkspaceListQuery,
)
register_response_schema_models(
    openapi_ns,
    ErrorBody,
    EventStreamResponse,
    SimpleResultResponse,
    UsageInfo,
    MessageMetadata,
    Hint,
    AppListRow,
    AppListResponse,
    AppInfo,
    AppDescribeInfo,
    AppDescribeResponse,
    AppDslExportResponse,
    Import,
    AppDslImportResponse,
    DslIssueRow,
    DslCheckResponse,
    ReleaseCheckResponse,
    CheckDependenciesResult,
    CheckDependenciesResponse,
    WorkflowRunData,
    AccountPayload,
    WorkspacePayload,
    AccountResponse,
    SessionRow,
    SessionListResponse,
    PermittedExternalAppsListResponse,
    RevokeResponse,
    WorkspaceSummaryResponse,
    WorkspaceListResponse,
    WorkspaceDetailResponse,
    MemberResponse,
    MemberListResponse,
    MemberInviteResponse,
    MemberActionResponse,
    TaskStopResponse,
    FormSubmitResponse,
    HumanInputFormDefinitionResponse,
    DeviceCodeResponse,
    DeviceTokenResponse,
    DeviceLookupResponse,
    DeviceMutateResponse,
    DeviceFlowErrorResponse,
    FileResponse,
    ServerVersionResponse,
    HealthResponse,
    RunListResponse,
    PublishResponse,
    VersionListResponse,
    RestoreResponse,
    EnvVariableListResponse,
    WorkflowRunDetailResponse,
    WorkflowRunNodeExecutionListResponse,
    WorkflowRunNodeExecutionResponse,
    CreatedAppResponse,
    NodeTypeRow,
    NodeTypeListResponse,
    NodeTypeDetailResponse,
    AppSettingsInfo,
    ChatAppInfo,
    AgentAppInfo,
    ServiceApi,
    AgentServiceApi,
    AdvancedChatWebApp,
    AgentWebApp,
    ChatWebApp,
    WebApp,
    WebAppAccess,
    WebAppToken,
    WorkflowWebApp,
    MarketplacePluginRow,
    MarketplacePluginListResponse,
    PluginProvides,
    PluginRow,
    PluginListResponse,
    PluginTaskStartResponse,
    PluginTaskItem,
    PluginTaskResponse,
    PluginDeleteResponse,
    CredentialFormField,
    CredentialRef,
    CredentialWriteResponse,
    CustomModelRow,
    ModelListResponse,
    ToolListResponse,
    ModelProviderDetailResponse,
    ModelProviderRow,
    ModelRow,
    KnowledgeBaseListResponse,
    KnowledgeBaseRow,
    KnowledgeRetrievalFragment,
    LlmModelBlock,
    MultipleRetrievalFragment,
    ToolProviderDetailResponse,
    ToolProviderRow,
)
# Standalone definition for contract codegen; ErrorBody.code stays an open
# string on the wire so old clients keep parsing future codes.
register_enum_models(openapi_ns, OpenApiErrorCode)

from . import (
    account,
    app_create,
    app_dsl,
    app_info,
    app_release,
    app_run,
    app_webapp,
    app_workflow,
    apps,
    apps_permitted_external,
    files,
    human_input_form,
    index,
    knowledge_bases,
    model_providers,
    node_types,
    oauth_device,
    oauth_device_sso,
    plugins,
    tool_providers,
    workflow_events,
    workspaces,
)

# Request models are imported from _models.py and registered above.

__all__ = [
    "account",
    "app_create",
    "app_dsl",
    "app_info",
    "app_release",
    "app_run",
    "app_webapp",
    "app_workflow",
    "apps",
    "apps_permitted_external",
    "files",
    "human_input_form",
    "index",
    "knowledge_bases",
    "model_providers",
    "node_types",
    "oauth_device",
    "oauth_device_sso",
    "plugins",
    "tool_providers",
    "workflow_events",
    "workspaces",
]

api.add_namespace(openapi_ns)