Phase 5.14: API documentation - OpenAPI tags, response models, examples, docs

app/main.py

@@ -212,7 +212,63 @@ async def lifespan(app: FastAPI):
 def create_app() -> FastAPI:
     """Create and configure the FastAPI application."""
     settings = get_settings()
-    app = FastAPI(title="LeoCRM", version="1.0.0", lifespan=lifespan)
+    app = FastAPI(
+        title="LeoCRM",
+        version="1.0.0",
+        lifespan=lifespan,
+        description=(
+            "LeoCRM — Self-hosted CRM system for small sales teams.\n\n"
+            "## Authentication\n"
+            "All endpoints (except `/api/v1/auth/login` and `/api/v1/health`) require "
+            "a valid session cookie. Obtain a session by calling `POST /api/v1/auth/login`.\n\n"
+            "## Multi-Tenancy\n"
+            "All data is tenant-scoped. The tenant context is set automatically from the "
+            "authenticated session.\n\n"
+            "## Plugins\n"
+            "LeoCRM uses a plugin architecture. Core routes are always available. "
+            "Plugin routes (DMS, Mail, Calendar, Automation, etc.) are registered when "
+            "the corresponding plugin is active."
+        ),
+        openapi_tags=[
+            {"name": "health", "description": "Health check endpoints — no auth required."},
+            {"name": "metrics", "description": "Prometheus metrics endpoint."},
+            {"name": "auth", "description": "Authentication: login, logout, session, password reset."},
+            {"name": "users", "description": "User management: CRUD, user-tenant assignments."},
+            {"name": "roles", "description": "Role management and permission definitions."},
+            {"name": "groups", "description": "User groups for contact assignment and filtering."},
+            {"name": "tenants", "description": "Tenant management and tenant switching."},
+            {"name": "notifications", "description": "User notifications and notification preferences."},
+            {"name": "contacts", "description": "Contact CRUD, contact persons, FTS search, export, soft-delete."},
+            {"name": "contact-folders", "description": "Contact folder management for organization."},
+            {"name": "entity-history", "description": "Audit trail and entity change history."},
+            {"name": "import-export", "description": "Bulk import and export of contacts and data."},
+            {"name": "plugins", "description": "Plugin management: list, install, activate, deactivate."},
+            {"name": "ai-copilot", "description": "AI copilot: chat, suggestions, conversation history."},
+            {"name": "workflows", "description": "Workflow definitions, instances, and execution."},
+            {"name": "user-preferences", "description": "Per-user preference settings."},
+            {"name": "currencies", "description": "Currency management for multi-currency support."},
+            {"name": "taxes", "description": "Tax rate management (VAT, sales tax)."},
+            {"name": "sequences", "description": "Number sequence management for invoices, quotes, etc."},
+            {"name": "system-settings", "description": "Tenant-level system settings (company info, theme)."},
+            {"name": "attachments", "description": "File attachments for contacts, companies, and entities."},
+            {"name": "addresses", "description": "Address management for contacts and companies."},
+            {"name": "audit", "description": "Audit log queries and compliance reporting."},
+            {"name": "automation", "description": "Automation engine: agents, automations, cron jobs, execution logs."},
+            {"name": "agents", "description": "AI agent definitions and agent runner endpoints."},
+            {"name": "dms", "description": "Document Management System: files, folders, sources, sharing."},
+            {"name": "mail", "description": "Email integration: IMAP accounts, folders, messages, send."},
+            {"name": "calendar", "description": "Calendar management: appointments, resources, recurrence."},
+            {"name": "search", "description": "Unified search across contacts, documents, emails, etc."},
+            {"name": "reports", "description": "Report generator: templates, rendering, scheduled reports."},
+            {"name": "entity-links", "description": "Entity linking: connect contacts to DMS documents and other entities."},
+            {"name": "kommunikation", "description": "Unified messaging: conversations, participants, messages."},
+            {"name": "ai-proactive", "description": "Proactive AI: insights, alerts, and recommendations."},
+            {"name": "ai-assistant", "description": "AI assistant: chat completions, tool calling, context awareness."},
+            {"name": "tags", "description": "Tag management: create, assign, search tags across entities."},
+            {"name": "permissions", "description": "Permission management: roles, field-level permissions, sharing."},
+            {"name": "public-share", "description": "Public sharing endpoints — no auth required, token-based access."},
+        ],
+    )
 
     app.add_middleware(
         CORSMiddleware,