autofix

.github/workflows/autofix.yml

@@ -116,6 +116,12 @@ jobs:
         if: github.event_name != 'merge_group'
         uses: ./.github/actions/setup-web
 
+      - name: Generate API docs
+        if: github.event_name != 'merge_group' && steps.api-changes.outputs.any_changed == 'true'
+        run: |
+          cd api
+          uv run dev/generate_swagger_markdown_docs.py --swagger-dir openapi --markdown-dir openapi/markdown
+
       - name: ESLint autofix
         if: github.event_name != 'merge_group' && steps.web-changes.outputs.any_changed == 'true'
         run: |

api/controllers/common/schema.py

@@ -1,4 +1,10 @@
-"""Helpers for registering Pydantic models with Flask-RESTX namespaces."""
+"""Helpers for registering Pydantic models with Flask-RESTX namespaces.
+
+Flask-RESTX treats `SchemaModel` bodies as opaque JSON schemas; it does not
+promote Pydantic's nested `$defs` into top-level Swagger `definitions`.
+These helpers keep that translation centralized so models registered through
+`register_schema_models` emit resolvable Swagger 2.0 references.
+"""
 
 from enum import StrEnum
 
@@ -8,10 +14,32 @@ from pydantic import BaseModel, TypeAdapter
 DEFAULT_REF_TEMPLATE_SWAGGER_2_0 = "#/definitions/{model}"
 
 
-def register_schema_model(namespace: Namespace, model: type[BaseModel]) -> None:
-    """Register a single BaseModel with a namespace for Swagger documentation."""
+def _register_json_schema(namespace: Namespace, name: str, schema: dict) -> None:
+    """Register a JSON schema and promote any nested Pydantic `$defs`."""
 
-    namespace.schema_model(model.__name__, model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0))
+    nested_definitions = schema.get("$defs")
+    schema_to_register = dict(schema)
+    if isinstance(nested_definitions, dict):
+        schema_to_register.pop("$defs")
+
+    namespace.schema_model(name, schema_to_register)
+
+    if not isinstance(nested_definitions, dict):
+        return
+
+    for nested_name, nested_schema in nested_definitions.items():
+        if isinstance(nested_schema, dict):
+            _register_json_schema(namespace, nested_name, nested_schema)
+
+
+def register_schema_model(namespace: Namespace, model: type[BaseModel]) -> None:
+    """Register a BaseModel and its nested schema definitions for Swagger documentation."""
+
+    _register_json_schema(
+        namespace,
+        model.__name__,
+        model.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0),
+    )
 
 
 def register_schema_models(namespace: Namespace, *models: type[BaseModel]) -> None:
@@ -34,8 +62,10 @@ def get_or_create_model(model_name: str, field_def):
 def register_enum_models(namespace: Namespace, *models: type[StrEnum]) -> None:
     """Register multiple StrEnum with a namespace."""
     for model in models:
-        namespace.schema_model(
-            model.__name__, TypeAdapter(model).json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0)
+        _register_json_schema(
+            namespace,
+            model.__name__,
+            TypeAdapter(model).json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0),
         )
 
 

api/controllers/console/admin.py

@@ -12,6 +12,7 @@ from werkzeug.exceptions import BadRequest, NotFound, Unauthorized
 
 from configs import dify_config
 from constants.languages import supported_language
+from controllers.common.schema import register_schema_models
 from controllers.console import console_ns
 from controllers.console.wraps import only_edition_cloud
 from core.db.session_factory import session_factory
@@ -301,15 +302,7 @@ class BatchAddNotificationAccountsPayload(BaseModel):
     user_email: list[str] = Field(..., description="List of account email addresses")
 
 
-console_ns.schema_model(
-    UpsertNotificationPayload.__name__,
-    UpsertNotificationPayload.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0),
-)
-
-console_ns.schema_model(
-    BatchAddNotificationAccountsPayload.__name__,
-    BatchAddNotificationAccountsPayload.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0),
-)
+register_schema_models(console_ns, UpsertNotificationPayload, BatchAddNotificationAccountsPayload)
 
 
 @console_ns.route("/admin/upsert_notification")

api/controllers/console/app/app_import.py

@@ -2,7 +2,7 @@ from flask_restx import Resource
 from pydantic import BaseModel, Field
 from sqlalchemy.orm import Session
 
-from controllers.common.schema import register_schema_models
+from controllers.common.schema import register_enum_models, register_schema_models
 from controllers.console.app.wraps import get_app_model
 from controllers.console.wraps import (
     account_initialization_required,
@@ -33,6 +33,7 @@ class AppImportPayload(BaseModel):
     app_id: str | None = Field(None)
 
 
+register_enum_models(console_ns, ImportStatus)
 register_schema_models(console_ns, AppImportPayload, Import, CheckDependenciesResult)
 
 

api/controllers/console/app/generator.py

@@ -3,6 +3,7 @@ from collections.abc import Sequence
 from flask_restx import Resource
 from pydantic import BaseModel, Field
 
+from controllers.common.schema import register_enum_models, register_schema_models
 from controllers.console import console_ns
 from controllers.console.app.error import (
     CompletionRequestError,
@@ -19,13 +20,12 @@ from core.helper.code_executor.python3.python3_code_provider import Python3CodeP
 from core.llm_generator.entities import RuleCodeGeneratePayload, RuleGeneratePayload, RuleStructuredOutputPayload
 from core.llm_generator.llm_generator import LLMGenerator
 from extensions.ext_database import db
+from graphon.model_runtime.entities.llm_entities import LLMMode
 from graphon.model_runtime.errors.invoke import InvokeError
 from libs.login import current_account_with_tenant, login_required
 from models import App
 from services.workflow_service import WorkflowService
 
-DEFAULT_REF_TEMPLATE_SWAGGER_2_0 = "#/definitions/{model}"
-
 
 class InstructionGeneratePayload(BaseModel):
     flow_id: str = Field(..., description="Workflow/Flow ID")
@@ -41,16 +41,16 @@ class InstructionTemplatePayload(BaseModel):
     type: str = Field(..., description="Instruction template type")
 
 
-def reg(cls: type[BaseModel]):
-    console_ns.schema_model(cls.__name__, cls.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0))
-
-
-reg(RuleGeneratePayload)
-reg(RuleCodeGeneratePayload)
-reg(RuleStructuredOutputPayload)
-reg(InstructionGeneratePayload)
-reg(InstructionTemplatePayload)
-reg(ModelConfig)
+register_enum_models(console_ns, LLMMode)
+register_schema_models(
+    console_ns,
+    RuleGeneratePayload,
+    RuleCodeGeneratePayload,
+    RuleStructuredOutputPayload,
+    InstructionGeneratePayload,
+    InstructionTemplatePayload,
+    ModelConfig,
+)
 
 
 @console_ns.route("/rule-generate")

api/dev/generate_swagger_markdown_docs.py

@@ -0,0 +1,84 @@
+"""Generate Swagger JSON specs and Markdown API docs.
+
+The Markdown step uses `swagger-markdown`, the same converter family as the
+Swagger Markdown UI, so CI and local regeneration catch converter-incompatible
+Swagger output early.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import subprocess
+import sys
+from pathlib import Path
+
+API_ROOT = Path(__file__).resolve().parents[1]
+if str(API_ROOT) not in sys.path:
+    sys.path.insert(0, str(API_ROOT))
+
+from dev.generate_swagger_specs import SPEC_TARGETS, generate_specs
+
+logger = logging.getLogger(__name__)
+
+SWAGGER_MARKDOWN_PACKAGE = "swagger-markdown@3.0.0"
+
+
+def generate_markdown_docs(swagger_dir: Path, markdown_dir: Path) -> list[Path]:
+    """Generate Swagger JSON files, convert each one to Markdown, and return Markdown paths."""
+
+    swagger_paths = generate_specs(swagger_dir)
+    swagger_paths_by_name = {path.name: path for path in swagger_paths}
+
+    markdown_dir.mkdir(parents=True, exist_ok=True)
+
+    written_paths: list[Path] = []
+    for target in SPEC_TARGETS:
+        swagger_path = swagger_paths_by_name[target.filename]
+        markdown_path = markdown_dir / f"{swagger_path.stem}.md"
+        subprocess.run(
+            [
+                "npx",
+                "--yes",
+                SWAGGER_MARKDOWN_PACKAGE,
+                "-i",
+                str(swagger_path),
+                "-o",
+                str(markdown_path),
+            ],
+            check=True,
+        )
+        written_paths.append(markdown_path)
+
+    return written_paths
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--swagger-dir",
+        type=Path,
+        default=Path("openapi"),
+        help="Directory where Swagger JSON files will be written.",
+    )
+    parser.add_argument(
+        "--markdown-dir",
+        type=Path,
+        default=Path("openapi/markdown"),
+        help="Directory where Markdown API docs will be written.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    written_paths = generate_markdown_docs(args.swagger_dir, args.markdown_dir)
+
+    for path in written_paths:
+        logger.debug(path)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

api/dev/generate_swagger_specs.py

@@ -13,8 +13,10 @@ import json
 import logging
 import os
 import sys
+from collections.abc import MutableMapping
 from dataclasses import dataclass
 from pathlib import Path
+from typing import Protocol
 
 from flask import Flask
 from flask_restx.swagger import Swagger
@@ -30,12 +32,19 @@ if str(API_ROOT) not in sys.path:
 class SpecTarget:
     route: str
     filename: str
+    namespace: str
+
+
+class RestxApi(Protocol):
+    models: MutableMapping[str, object]
+
+    def model(self, name: str, model: dict[object, object]) -> object: ...
 
 
 SPEC_TARGETS: tuple[SpecTarget, ...] = (
-    SpecTarget(route="/console/api/swagger.json", filename="console-swagger.json"),
-    SpecTarget(route="/api/swagger.json", filename="web-swagger.json"),
-    SpecTarget(route="/v1/swagger.json", filename="service-swagger.json"),
+    SpecTarget(route="/console/api/swagger.json", filename="console-swagger.json", namespace="console"),
+    SpecTarget(route="/api/swagger.json", filename="web-swagger.json", namespace="web"),
+    SpecTarget(route="/v1/swagger.json", filename="service-swagger.json", namespace="service"),
 )
 
 _ORIGINAL_REGISTER_MODEL = Swagger.register_model
@@ -74,7 +83,7 @@ def _patch_swagger_for_inline_nested_dicts() -> None:
         anonymous_models = getattr(self, "_anonymous_inline_models", None)
         if anonymous_models is None:
             anonymous_models = {}
-            self._anonymous_inline_models = anonymous_models
+            self.__dict__["_anonymous_inline_models"] = anonymous_models
 
         anonymous_name = anonymous_models.get(id(nested_fields))
         if anonymous_name is None:
@@ -121,6 +130,108 @@ def create_spec_app() -> Flask:
     return app
 
 
+def _registered_models(namespace: str) -> dict[str, object]:
+    """Return the Flask-RESTX models registered for a Swagger namespace."""
+
+    if namespace == "console":
+        from controllers.console import console_ns
+
+        for api in console_ns.apis:
+            _materialize_inline_model_definitions(api)
+        models = dict(console_ns.models)
+        for api in console_ns.apis:
+            models.update(api.models)
+        return models
+    if namespace == "web":
+        from controllers.web import web_ns
+
+        for api in web_ns.apis:
+            _materialize_inline_model_definitions(api)
+        models = dict(web_ns.models)
+        for api in web_ns.apis:
+            models.update(api.models)
+        return models
+    if namespace == "service":
+        from controllers.service_api import service_api_ns
+
+        for api in service_api_ns.apis:
+            _materialize_inline_model_definitions(api)
+        models = dict(service_api_ns.models)
+        for api in service_api_ns.apis:
+            models.update(api.models)
+        return models
+
+    raise ValueError(f"unknown Swagger namespace: {namespace}")
+
+
+def _materialize_inline_model_definitions(api: RestxApi) -> None:
+    """Convert inline `fields.Nested({...})` maps into named API models."""
+
+    from flask_restx import fields
+    from flask_restx.model import Model, OrderedModel, instance
+
+    anonymous_models: dict[int, str] = {}
+    next_anonymous_index = 1
+
+    def model_name_for(nested_fields: dict[object, object]) -> str:
+        nonlocal next_anonymous_index
+
+        anonymous_name = anonymous_models.get(id(nested_fields))
+        if anonymous_name is None:
+            anonymous_name = f"_AnonymousInlineModel{next_anonymous_index}"
+            while anonymous_name in api.models:
+                next_anonymous_index += 1
+                anonymous_name = f"_AnonymousInlineModel{next_anonymous_index}"
+            anonymous_models[id(nested_fields)] = anonymous_name
+            next_anonymous_index += 1
+            api.model(anonymous_name, nested_fields)
+        return anonymous_name
+
+    def materialize_field(field: object) -> None:
+        field_instance = instance(field)
+        if isinstance(field_instance, fields.Nested):
+            nested = getattr(field_instance, "nested", None)
+            if isinstance(nested, dict):
+                field_instance.model = api.models[model_name_for(nested)]  # type: ignore[attr-defined]
+
+        container = getattr(field_instance, "container", None)
+        if container is not None:
+            materialize_field(container)
+
+    index = 0
+    while index < len(api.models):
+        model = list(api.models.values())[index]
+        index += 1
+        if isinstance(model, (Model, OrderedModel)):
+            for field in model.values():
+                materialize_field(field)
+
+
+def _drop_null_values(value: object) -> object:
+    """Remove JSON null values that make the Markdown converter crash."""
+
+    if isinstance(value, dict):
+        return {key: _drop_null_values(item) for key, item in value.items() if item is not None}
+    if isinstance(value, list):
+        return [_drop_null_values(item) for item in value]
+    return value
+
+
+def _merge_registered_definitions(payload: dict[str, object], namespace: str) -> dict[str, object]:
+    """Include registered but route-indirect models in the exported Swagger definitions."""
+
+    definitions = payload.setdefault("definitions", {})
+    if not isinstance(definitions, dict):
+        raise RuntimeError("unexpected Swagger definitions payload")
+
+    for name, model in _registered_models(namespace).items():
+        schema = getattr(model, "__schema__", None)
+        if isinstance(schema, dict):
+            definitions.setdefault(name, schema)
+
+    return payload
+
+
 def generate_specs(output_dir: Path) -> list[Path]:
     """Write all Swagger specs to `output_dir` and return the written paths."""
 
@@ -138,6 +249,8 @@ def generate_specs(output_dir: Path) -> list[Path]:
         payload = response.get_json()
         if not isinstance(payload, dict):
             raise RuntimeError(f"unexpected response payload for {target.route}")
+        payload = _merge_registered_definitions(payload, target.namespace)
+        payload = _drop_null_values(payload)
 
         output_path = output_dir / target.filename
         output_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")

api/tests/unit_tests/commands/test_generate_swagger_specs.py

@@ -6,6 +6,16 @@ import sys
 from pathlib import Path
 
 
+def _walk_values(value):
+    yield value
+    if isinstance(value, dict):
+        for child in value.values():
+            yield from _walk_values(child)
+    elif isinstance(value, list):
+        for child in value:
+            yield from _walk_values(child)
+
+
 def _load_generate_swagger_specs_module():
     api_dir = Path(__file__).resolve().parents[3]
     script_path = api_dir / "dev" / "generate_swagger_specs.py"
@@ -35,3 +45,21 @@ def test_generate_specs_writes_console_web_and_service_swagger_files(tmp_path):
         payload = json.loads(path.read_text(encoding="utf-8"))
         assert payload["swagger"] == "2.0"
         assert "paths" in payload
+
+
+def test_generate_specs_writes_swagger_with_resolvable_references_and_no_nulls(tmp_path):
+    module = _load_generate_swagger_specs_module()
+
+    written_paths = module.generate_specs(tmp_path)
+
+    for path in written_paths:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        definitions = payload["definitions"]
+        refs = {
+            item["$ref"].removeprefix("#/definitions/")
+            for item in _walk_values(payload)
+            if isinstance(item, dict) and isinstance(item.get("$ref"), str)
+        }
+
+        assert refs <= set(definitions)
+        assert all(value is not None for value in _walk_values(payload))

api/tests/unit_tests/controllers/common/test_schema.py

@@ -17,6 +17,14 @@ class ProductModel(BaseModel):
     price: float
 
 
+class ChildModel(BaseModel):
+    value: str
+
+
+class ParentModel(BaseModel):
+    child: ChildModel
+
+
 @pytest.fixture(autouse=True)
 def mock_console_ns():
     """Mock the console_ns to avoid circular imports during test collection."""
@@ -64,6 +72,22 @@ def test_register_schema_model_passes_schema_from_pydantic():
     assert schema == expected_schema
 
 
+def test_register_schema_model_promotes_nested_pydantic_definitions():
+    from controllers.common.schema import DEFAULT_REF_TEMPLATE_SWAGGER_2_0, register_schema_model
+
+    namespace = MagicMock(spec=Namespace)
+
+    register_schema_model(namespace, ParentModel)
+
+    called_schemas = {call.args[0]: call.args[1] for call in namespace.schema_model.call_args_list}
+    parent_schema = ParentModel.model_json_schema(ref_template=DEFAULT_REF_TEMPLATE_SWAGGER_2_0)
+
+    assert set(called_schemas) == {"ParentModel", "ChildModel"}
+    assert "$defs" not in called_schemas["ParentModel"]
+    assert called_schemas["ParentModel"]["properties"]["child"]["$ref"] == "#/definitions/ChildModel"
+    assert called_schemas["ChildModel"] == parent_schema["$defs"]["ChildModel"]
+
+
 def test_register_schema_models_registers_multiple_models():
     from controllers.common.schema import register_schema_models