docs(api): add internal API contract and expose response schemas in swagger

app/schemas/internal.py

@@ -0,0 +1,85 @@
+from pydantic import BaseModel
+
+
+class InternalSystemItem(BaseModel):
+    id: str
+    system_key: str
+    name: str
+    status: str
+
+
+class InternalSystemListResponse(BaseModel):
+    items: list[InternalSystemItem]
+    total: int
+    limit: int
+    offset: int
+
+
+class InternalModuleItem(BaseModel):
+    id: str
+    module_key: str
+    system_key: str
+    name: str
+    status: str
+
+
+class InternalModuleListResponse(BaseModel):
+    items: list[InternalModuleItem]
+    total: int
+    limit: int
+    offset: int
+
+
+class InternalCompanyItem(BaseModel):
+    id: str
+    company_key: str
+    name: str
+    status: str
+
+
+class InternalCompanyListResponse(BaseModel):
+    items: list[InternalCompanyItem]
+    total: int
+    limit: int
+    offset: int
+
+
+class InternalSiteItem(BaseModel):
+    id: str
+    site_key: str
+    company_key: str | None = None
+    name: str
+    status: str
+
+
+class InternalSiteListResponse(BaseModel):
+    items: list[InternalSiteItem]
+    total: int
+    limit: int
+    offset: int
+
+
+class InternalMemberItem(BaseModel):
+    id: str
+    authentik_sub: str
+    username: str | None = None
+    email: str | None = None
+    display_name: str | None = None
+    is_active: bool
+
+
+class InternalMemberListResponse(BaseModel):
+    items: list[InternalMemberItem]
+    total: int
+    limit: int
+    offset: int
+
+
+class InternalUpsertUserBySubResponse(BaseModel):
+    id: str
+    sub: str
+    authentik_user_id: int | None = None
+    username: str | None = None
+    email: str | None = None
+    display_name: str | None = None
+    is_active: bool