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

app/api/internal.py

@@ -4,6 +4,7 @@ from sqlalchemy.orm import Session
 from app.core.config import get_settings
 from app.db.session import get_db
 from app.repositories.permissions_repo import PermissionsRepository
+from app.schemas.internal import InternalUpsertUserBySubResponse
 from app.repositories.users_repo import UsersRepository
 from app.schemas.authentik_admin import AuthentikEnsureUserRequest, AuthentikEnsureUserResponse
 from app.schemas.permissions import PermissionSnapshotResponse
@@ -15,11 +16,11 @@ from app.services.permission_service import PermissionService
 router = APIRouter(prefix="/internal", tags=["internal"], dependencies=[Depends(require_api_client)])
 
 
-@router.post("/users/upsert-by-sub")
+@router.post("/users/upsert-by-sub", response_model=InternalUpsertUserBySubResponse)
 def upsert_user_by_sub(
     payload: UserUpsertBySubRequest,
     db: Session = Depends(get_db),
-) -> dict[str, str | bool | None]:
+) -> InternalUpsertUserBySubResponse:
     repo = UsersRepository(db)
     user = repo.upsert_by_sub(
         authentik_sub=payload.sub,