doc: enhanced the auth route documentation

API/auth/routers.py

@@ -5,12 +5,17 @@
 
 from src.app import Users
 
+from src.validation.models import (
+    LoginResponse,
+    CallbackResponse
+)
+
 from . import AuthUser, admin_required, login_required, osm_auth, staff_required
 
 router = APIRouter(prefix="/auth", tags=["Auth"])
 
 
-@router.get("/login/")
+@router.get("/login/", response_model=LoginResponse)
 def login_url(request: Request):
     """Generate Login URL for authentication using OAuth2 Application registered with OpenStreetMap.
     Click on the download url returned to get access_token.
@@ -25,13 +30,16 @@ def login_url(request: Request):
     return login_url
 
 
-@router.get("/callback/")
+@router.get("/callback/", response_model=CallbackResponse)
 def callback(request: Request):
     """Performs token exchange between OpenStreetMap and Raw Data API
 
     Core will use Oauth secret key from configuration while deserializing token,
     provides access token that can be used for authorized endpoints.
 
+    This endpoint handles the OAuth callback after the user has authorized the
+    application by visiting the link generated by the by the `/auth/login/` route
+
     Parameters: None
 
     Returns:
@@ -81,6 +89,7 @@ async def create_user(params: User, user_data: AuthUser = Depends(admin_required
 
     Raises:
     - HTTPException: If the user creation fails.
+    - HTTPException(403): User is not an admin (Forbidden).
     """
     auth = Users()
     return auth.create_user(params.osm_id, params.role)
@@ -104,6 +113,7 @@ async def read_user(osm_id: int, user_data: AuthUser = Depends(staff_required)):
 
     Raises:
     - HTTPException: If the user with the given osm_id is not found.
+    - HTTPException(403): User is not a staff (Forbidden).
     """
     auth = Users()
 
@@ -149,6 +159,7 @@ async def delete_user(osm_id: int, user_data: AuthUser = Depends(admin_required)
 
     Raises:
     - HTTPException: If the user with the given osm_id is not found.
+    - HTTPException(403): User is not an admin (Forbidden).
     """
     auth = Users()
     return auth.delete_user(osm_id)
@@ -168,6 +179,9 @@ async def read_users(
 
     Returns:
     - List[Dict[str, Any]]: A list of dictionaries containing user information.
+
+    Raises:
+    - HTTPException(403): User is not a staff (Forbidden).
     """
     auth = Users()
     return auth.read_users(skip, limit)

Dockerfile

@@ -66,7 +66,7 @@ USER appuser
 # API and source code, changes here don't invalidate previous layers , You can overwrite this block with -v
 
 # Copy config.txt if you have your configuration setup in config
-# COPY config.txt .
+COPY config.txt ./config.txt
 COPY README.md .
 COPY setup.py .
 COPY pyproject.toml .

docker-compose-config.txt

@@ -18,4 +18,4 @@ OSM_CLIENT_SECRET=
 OSM_URL=https://www.openstreetmap.org
 OSM_PERMISSION_SCOPE=read_prefs
 LOGIN_REDIRECT_URI=http://127.0.0.1:8000/v1/auth/callback
-APP_SECRET_KEY=replace_this_with_your_trusted_secret_key
+APP_SECRET_KEY=

src/validation/models.py

@@ -291,6 +291,11 @@ class StatusResponse(BaseModel):
     class Config:
         json_schema_extra = {"example": {"lastUpdated": "2022-06-27 19:59:24+05:45"}}
 
+class LoginResponse(BaseModel):
+    login_url: str = Field(alias="login_url")
+
+class CallbackResponse(BaseModel):
+    access_token: str = Field(alias="access_token")
 
 class StatsRequestParams(BaseModel, GeometryValidatorMixin):
     iso3: Optional[str] = Field(