Annotate FastAPI routes for better OpenAPI documentation

Author: chriscarrollsmith

routers/core/account.py

@@ -61,8 +61,8 @@
 
 
 def validate_password_strength_and_match(
-    password: str = Form(...),
-    confirm_password: str = Form(...)
+    password: str = Form(..., title="Password", description="Account password"),
+    confirm_password: str = Form(..., title="Confirm password", description="Re-enter password to confirm")
 ) -> str:
     """
     Validates password strength and confirms passwords match.
@@ -120,9 +120,9 @@ async def read_login(
     if user:
         return RedirectResponse(url=dashboard_router.url_path_for("read_dashboard"), status_code=302)
     return templates.TemplateResponse(
+        request,
         "account/login.html",
         {
-            "request": request,
             "user": user,
             "invitation_token": invitation_token
         }
@@ -143,9 +143,9 @@ async def read_register(
         return RedirectResponse(url=dashboard_router.url_path_for("read_dashboard"), status_code=302)
 
     return templates.TemplateResponse(
+        request,
         "account/register.html",
         {
-            "request": request,
             "user": user,
             "password_pattern": HTML_PASSWORD_PATTERN,
             "email": email,
@@ -167,8 +167,9 @@ async def read_forgot_password(
         return RedirectResponse(url=dashboard_router.url_path_for("read_dashboard"), status_code=302)
 
     return templates.TemplateResponse(
+        request,
         "account/forgot_password.html",
-        {"request": request, "user": user, "show_form": show_form == "true"}
+        {"user": user, "show_form": show_form == "true"}
     )
 
 
@@ -190,15 +191,16 @@ async def read_reset_password(
         raise CredentialsError(message="Invalid or expired token")
 
     return templates.TemplateResponse(
+        request,
         "account/reset_password.html",
-        {"request": request, "user": user, "email": email, "token": token, "password_pattern": HTML_PASSWORD_PATTERN}
+        {"user": user, "email": email, "token": token, "password_pattern": HTML_PASSWORD_PATTERN}
     )
 
 
 @router.post("/delete", response_class=RedirectResponse)
 async def delete_account(
-    email: EmailStr = Form(...),
-    password: str = Form(...),
+    email: EmailStr = Form(..., title="Email", description="Account email address for verification"),
+    password: str = Form(..., title="Password", description="Account password for verification"),
     account: Account = Depends(get_authenticated_account),
     session: Session = Depends(get_session)
 ):
@@ -229,12 +231,12 @@ async def delete_account(
 async def register(
     request: Request,
     _ip_check: None = Depends(check_register_ip_rate_limit),
-    name: str = Form(...),
-    email: EmailStr = Form(...),
+    name: str = Form(..., min_length=1, strip_whitespace=True, title="Name", description="Your full name"),
+    email: EmailStr = Form(..., title="Email", description="Email address for the new account"),
     session: Session = Depends(get_session),
     _: None = Depends(validate_password_strength_and_match),
-    password: str = Form(...),
-    invitation_token: Optional[str] = Form(None)
+    password: str = Form(..., title="Password", description="Account password"),
+    invitation_token: Optional[str] = Form(None, title="Invitation token", description="Optional invitation token to join an organization")
 ) -> Response:
     """
     Register a new user account, optionally processing an invitation.
@@ -353,7 +355,7 @@ async def login(
     _ip_check: None = Depends(check_login_ip_rate_limit),
     _email_check: EmailStr = Depends(check_login_email_rate_limit),
     account_and_session: Tuple[Account, Session] = Depends(get_account_from_credentials),
-    invitation_token: Optional[str] = Form(None)
+    invitation_token: Optional[str] = Form(None, title="Invitation token", description="Optional invitation token to join an organization after login")
 ) -> Response:
     """
     Log in a user with valid credentials and process invitation if token is provided.
@@ -534,8 +536,8 @@ async def forgot_password(
 @router.post("/reset_password")
 async def reset_password(
     request: Request,
-    email: EmailStr = Form(...),
-    token: str = Form(...),
+    email: EmailStr = Form(..., title="Email", description="Account email address"),
+    token: str = Form(..., title="Reset token", description="Password reset token from email"),
     new_password: str = Depends(validate_password_strength_and_match),
     session: Session = Depends(get_session)
 ):
@@ -569,8 +571,8 @@ async def reset_password(
 @router.post("/update_email")
 async def request_email_update(
     request: Request,
-    email: EmailStr = Form(...),
-    new_email: EmailStr = Form(...),
+    email: EmailStr = Form(..., title="Current email", description="Current account email address"),
+    new_email: EmailStr = Form(..., title="New email", description="New email address to update to"),
     account: Account = Depends(get_authenticated_account),
     session: Session = Depends(get_session)
 ):

routers/core/dashboard.py

@@ -17,6 +17,7 @@ async def read_dashboard(
     user: Optional[User] = Depends(get_user_with_relations)
 ):
     return templates.TemplateResponse(
+        request,
         "dashboard/index.html",
-        {"request": request, "user": user}
+        {"user": user}
     )

routers/core/invitation.py

@@ -54,9 +54,9 @@ async def create_invitation(
     request: Request,
     current_user: User = Depends(get_authenticated_user),
     session: Session = Depends(get_session),
-    invitee_email: EmailStr = Form(...),
-    role_id: int = Form(...),
-    organization_id: int = Form(...),
+    invitee_email: EmailStr = Form(..., title="Invitee email", description="Email address of the person to invite"),
+    role_id: int = Form(..., title="Role ID", description="ID of the role to assign to the invitee"),
+    organization_id: int = Form(..., title="Organization ID", description="ID of the organization to invite the user to"),
 ):
     # Fetch the organization
     organization = session.get(Organization, organization_id)

routers/core/role.py

@@ -1,6 +1,6 @@
 # TODO: User with permission to create/edit roles can only assign permissions
 # they themselves have.
-from typing import List, Sequence, Optional
+from typing import Annotated, List, Sequence, Optional
 from logging import getLogger
 from fastapi import APIRouter, Depends, Form, Request
 from fastapi.responses import RedirectResponse
@@ -43,9 +43,9 @@ def _load_org_for_roles_partial(session: Session, organization_id: int, user: Us
 @router.post("/create", response_class=RedirectResponse)
 def create_role(
     request: Request,
-    name: str = Form(...),
-    organization_id: int = Form(...),
-    permissions: List[ValidPermissions] = Form(default=[]),
+    name: Annotated[str, Form(min_length=1, strip_whitespace=True, title="Role name", description="Name for the new role")],
+    organization_id: int = Form(..., title="Organization ID", description="ID of the organization this role belongs to"),
+    permissions: List[ValidPermissions] = Form(default=[], title="Permissions", description="List of permissions to assign to this role"),
     user: User = Depends(get_authenticated_user),
     session: Session = Depends(get_session)
 ):
@@ -107,10 +107,10 @@ def create_role(
 @router.post("/update", response_class=RedirectResponse)
 def update_role(
     request: Request,
-    id: int = Form(...),
-    name: str = Form(...),
-    organization_id: int = Form(...),
-    permissions: List[ValidPermissions] = Form(default=[]),
+    id: int = Form(..., title="Role ID", description="ID of the role to update"),
+    name: str = Form(..., min_length=1, strip_whitespace=True, title="Role name", description="Updated name for the role"),
+    organization_id: int = Form(..., title="Organization ID", description="ID of the organization this role belongs to"),
+    permissions: List[ValidPermissions] = Form(default=[], title="Permissions", description="Updated list of permissions for this role"),
     user: User = Depends(get_authenticated_user),
     session: Session = Depends(get_session)
 ):
@@ -197,8 +197,8 @@ def update_role(
 @router.post("/delete", response_class=RedirectResponse)
 def delete_role(
     request: Request,
-    id: int = Form(...),
-    organization_id: int = Form(...),
+    id: int = Form(..., title="Role ID", description="ID of the role to delete"),
+    organization_id: int = Form(..., title="Organization ID", description="ID of the organization this role belongs to"),
     user: User = Depends(get_authenticated_user),
     session: Session = Depends(get_session)
 ):

routers/core/user.py

@@ -66,7 +66,7 @@ async def read_profile(
 @router.post("/update", response_class=RedirectResponse)
 async def update_profile(
     request: Request,
-    name: Optional[str] = Form(None),
+    name: Optional[str] = Form(None, strip_whitespace=True, title="Name", description="Updated display name"),
     avatar_file: Optional[UploadFile] = File(None),
     user: User = Depends(get_authenticated_user),
     session: Session = Depends(get_session)
@@ -133,9 +133,9 @@ async def get_avatar(
 @router.post("/role/update", response_class=RedirectResponse)
 def update_user_role(
     request: Request,
-    user_id: int = Form(...),
-    organization_id: int = Form(...),
-    roles: Optional[List[int]] = Form(None),
+    user_id: int = Form(..., title="User ID", description="ID of the user whose roles are being updated"),
+    organization_id: int = Form(..., title="Organization ID", description="ID of the organization"),
+    roles: Optional[List[int]] = Form(None, title="Role IDs", description="List of role IDs to assign to the user"),
     user: User = Depends(get_authenticated_user),
     session: Session = Depends(get_session)
 ) -> Response:
@@ -205,8 +205,8 @@ def update_user_role(
 @router.post("/organization/remove", response_class=RedirectResponse)
 def remove_user_from_organization(
     request: Request,
-    user_id: int = Form(...),
-    organization_id: int = Form(...),
+    user_id: int = Form(..., title="User ID", description="ID of the user to remove"),
+    organization_id: int = Form(..., title="Organization ID", description="ID of the organization to remove the user from"),
     user: User = Depends(get_authenticated_user),
     session: Session = Depends(get_session)
 ) -> Response: