docs(openapi): correct stale op summaries, examples and docstrings

api/controllers/openapi/_models.py

@@ -36,7 +36,7 @@ MAX_PAGE_LIMIT = 100
 
 
 class SupportedAppType(StrEnum):
-    """App types the ``app`` usage face (``get app``) lists and filters.
+    """App types the app list ops list and filter by.
 
     A curated subset of :class:`AppMode`: the real, user-facing app categories.
     Excludes runtime-only mode tags that are not standalone apps
@@ -45,8 +45,7 @@ class SupportedAppType(StrEnum):
 
     Members reference ``AppMode.*.value`` so the subset relationship is
     type-checked: dropping a member from ``AppMode`` breaks this at import.
-    This is the single source for the listable set — params, filters, and the
-    generated CLI whitelist all derive from it.
+    This is the single source for the listable set — params and filters derive from it.
     """
 
     COMPLETION = AppMode.COMPLETION.value
@@ -71,7 +70,7 @@ class MessageMetadata(BaseModel):
 
 
 class Hint(BaseModel):
-    """A next step the caller can hand straight to `call <op> --input <input>`."""
+    """A next step: the op id to call and its ready input."""
 
     summary: str
     op: str
@@ -142,7 +141,7 @@ class AppInfo(BaseModel):
 class AppDescribeInfo(AppInfo):
     updated_at: str | None = None
     service_api_enabled: bool
-    is_agent: bool = False
+    is_agent: bool = Field(False, description="True for agent-chat and advanced-chat apps")
 
 
 class AppDescribeResponse(Hinted):
@@ -330,7 +329,11 @@ class AppListQuery(PageQuery):
 
     workspace_id: UUIDStr
     mode: SupportedAppType | None = None
-    name: str | None = Field(None, max_length=200)
+    name: str | None = Field(
+        None,
+        max_length=200,
+        description="Filter by a name substring; an app id returns that one app and ignores `mode`",
+    )
 
 
 class _ConversationFields(BaseModel):

api/controllers/openapi/app_dsl.py

@@ -104,7 +104,9 @@ class AppDslImportApi(Resource):
 
     Returns 202 when the DSL version requires an explicit confirmation step
     (major version mismatch).  Callers must then POST to the imports :confirm method.
-    Returns 400 when the import failed due to invalid DSL or a business error.
+    Returns 400 with the ``Import`` body when the import failed (an unreachable URL,
+    unparsable DSL or a business error), 409 ``draft_changed`` when ``draft_hash`` no
+    longer matches the draft, and 422 ``dsl_invalid`` when the graph has errors.
     """
 
     @endpoint(
@@ -163,7 +165,7 @@ class AppDslImportApi(Resource):
 class AppDslCheckApi(Resource):
     """Check a DSL without importing it.
 
-    Errors are what the import refuses; warnings (missing credentials or models) are what publish refuses.
+    Errors are what the import refuses; warnings (missing credentials or models) are what the release check refuses.
     Pass ``app_id`` to check against an existing app's mode, as an overwrite import would.
     """
 

api/controllers/openapi/app_run.py

@@ -285,7 +285,7 @@ _RUN_ROUTES: Final = (
         resource="ChatRunApi",
         segment="chat",
         op="run.console_app.chat",
-        summary="Run a chat or agent app; streams message events",
+        summary="Run a chat or agent-chat app; streams message events",
         payload=ChatRunPayload,
         modes=(AppMode.CHAT, AppMode.AGENT_CHAT),
         hints=(_reply_layer,),

api/controllers/openapi/app_workflow.py

@@ -118,7 +118,7 @@ class AppRunListApi(Resource):
                 input={"app_id": "<app_id>", "status": "failed", "triggered_from": "app-run"},
             ),
             Example(
-                title="My latest draft test run",
+                title="The latest draft test run of this app, by anyone",
                 input={"app_id": "<app_id>", "triggered_from": "debugging", "limit": 1},
             ),
         ),

api/controllers/openapi/workspaces.py

@@ -118,12 +118,7 @@ class WorkspaceByIdApi(Resource):
 
 @openapi_ns.route("/workspaces/<string:workspace_id>:switch")
 class WorkspaceSwitchApi(Resource):
-    """Server-side switch — equivalent to the console's POST /workspaces/switch.
-
-    CLI `difyctl use workspace <id>` calls this; it does NOT mutate
-    ``hosts.yml`` on its own. Failure here must abort the local write so
-    that ``hosts.yml`` never diverges from the server's ``current`` state.
-    """
+    """Server-side switch — equivalent to the console's POST /workspaces/switch."""
 
     @endpoint(
         op="switch.workspace",