feat: 完善后端 API OpenAPI 文档与统一错误响应 schema

server/tests/test_openapi_schema.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from app.core.config import get_settings
+from app.main import create_app
+
+
+def test_openapi_schema_includes_documented_backend_routes() -> None:
+    schema = create_app().openapi()
+
+    assert schema["info"]["title"] == get_settings().app_name
+    assert any(tag["name"] == "agent-assets" for tag in schema["tags"])
+    assert any(tag["name"] == "knowledge" for tag in schema["tags"])
+
+    agent_assets_post = schema["paths"]["/api/v1/agent-assets"]["post"]
+    assert agent_assets_post["summary"] == "创建 Agent 资产"
+    assert any(param["name"] == "x-actor" for param in agent_assets_post["parameters"])
+
+    knowledge_upload_post = schema["paths"]["/api/v1/knowledge/documents"]["post"]
+    assert knowledge_upload_post["summary"] == "上传知识库文档"
+    assert "application/octet-stream" in knowledge_upload_post["requestBody"]["content"]
+
+    knowledge_callback_post = schema["paths"][
+        "/api/v1/knowledge/documents/{document_id}/onlyoffice/callback"
+    ]["post"]
+    assert knowledge_callback_post["summary"] == "接收 ONLYOFFICE 回调"
+    assert "application/json" in knowledge_callback_post["requestBody"]["content"]
+
+    root_get = schema["paths"]["/"]["get"]
+    assert root_get["summary"] == "服务根检查"