Api docs enhancements

API/auth/__init__.py

@@ -24,10 +24,12 @@ class AuthUser(BaseModel):
 
 osm_auth = Auth(*get_oauth_credentials())
 
-
 def get_user_from_db(osm_id: int):
     auth = Users()
     user = auth.read_user(osm_id)
+    # Add changes that when the User is not found in the Database 404 Error is raised
+    if not user:
+        raise HTTPException(status_code=404, detail="User not Found in the Database")
     return user
 
 

API/auth/responses.py

@@ -0,0 +1,24 @@
+from fastapi import HTTPException
+from pydantic import BaseModel
+
+# Define common error responses
+common_error_responses = {
+    403: {"description": "Forbidden", "model": HTTPException},
+    404: {"description": "Not Found", "model": HTTPException},
+    500: {"description": "Internal Server Error", "model": HTTPException},
+}
+
+# Define shared error response models
+class ErrorResponse(BaseModel):
+    detail: str
+
+# Add a default response model for error responses
+for status_code in common_error_responses:
+    if "model" not in common_error_responses[status_code]:
+        common_error_responses[status_code]["model"] = ErrorResponse
+
+error_responses_with_examples = {
+    403: {"content": {"application/json": {"example": {"message": "Access forbidden"}}}},
+    404: {"content": {"application/json": {"example": {"error": "Not Found"}}}},
+    500: {"content": {"application/json": {"example": {"error": "Internal Server Error"}}}},
+}

API/auth/routers.py

@@ -1,16 +1,19 @@
 import json
 
-from fastapi import APIRouter, Depends, Request
+from fastapi import APIRouter, Depends, Request, HTTPException
 from pydantic import BaseModel
 
 from src.app import Users
 
 from . import AuthUser, admin_required, login_required, osm_auth, staff_required
+from .responses import common_error_responses, error_responses_with_examples
 
 router = APIRouter(prefix="/auth", tags=["Auth"])
 
 
-@router.get("/login/")
+@router.get(
+    "/login", responses={**common_error_responses, **error_responses_with_examples}
+)
 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,7 +28,9 @@ def login_url(request: Request):
     return login_url
 
 
-@router.get("/callback/")
+@router.get(
+    "/callback", responses={**common_error_responses, **error_responses_with_examples}
+)
 def callback(request: Request):
     """Performs token exchange between OpenStreetMap and Raw Data API
 
@@ -37,12 +42,22 @@ def callback(request: Request):
     Returns:
     - access_token (string)
     """
-    access_token = osm_auth.callback(str(request.url))
+    try:
+        access_token = osm_auth.callback(str(request.url))
+    except Exception as ex:
+        raise HTTPException(
+            status_code=500,
+            detail="Internal Server Error occurred while performing token exchange between OpenStreetMap and Raw Data API",
+        )
 
     return access_token
 
 
-@router.get("/me/", response_model=AuthUser)
+@router.get(
+    "/me",
+    response_model=AuthUser,
+    responses={**common_error_responses, **error_responses_with_examples},
+)
 def my_data(user_data: AuthUser = Depends(login_required)):
     """Read the access token and provide  user details from OSM user's API endpoint,
     also integrated with underpass .
@@ -64,7 +79,11 @@ class User(BaseModel):
 
 
 # Create user
-@router.post("/users/", response_model=dict)
+@router.post(
+    "/users",
+    response_model=dict,
+    responses={**common_error_responses, **error_responses_with_examples},
+)
 async def create_user(params: User, user_data: AuthUser = Depends(admin_required)):
     """
     Creates a new user and returns the user's information.
@@ -87,7 +106,11 @@ async def create_user(params: User, user_data: AuthUser = Depends(admin_required
 
 
 # Read user by osm_id
-@router.get("/users/{osm_id}", response_model=dict)
+@router.get(
+    "/users/{osm_id}",
+    response_model=dict,
+    responses={**common_error_responses, **error_responses_with_examples},
+)
 async def read_user(osm_id: int, user_data: AuthUser = Depends(staff_required)):
     """
     Retrieves user information based on the given osm_id.
@@ -103,15 +126,20 @@ async def read_user(osm_id: int, user_data: AuthUser = Depends(staff_required)):
     - Dict[str, Any]: A dictionary containing user information.
 
     Raises:
-    - HTTPException: If the user with the given osm_id is not found.
+    - HTTPException 404: If the user with the given osm_id is not found.
+    - HTTPException 403: If the user is not a staff.
     """
     auth = Users()
 
     return auth.read_user(osm_id)
 
 
 # Update user by osm_id
-@router.put("/users/{osm_id}", response_model=dict)
+@router.put(
+    "/users/{osm_id}",
+    response_model=dict,
+    responses={**common_error_responses, **error_responses_with_examples},
+)
 async def update_user(
     osm_id: int, update_data: User, user_data: AuthUser = Depends(admin_required)
 ):
@@ -129,14 +157,19 @@ async def update_user(
     - Dict[str, Any]: A dictionary containing the updated user information.
 
     Raises:
-    - HTTPException: If the user with the given osm_id is not found.
+    - HTTPException 403: If the user is not an Admin.
+    - HTTPException 404: If the user with the given osm_id is not found.
     """
     auth = Users()
     return auth.update_user(osm_id, update_data)
 
 
 # Delete user by osm_id
-@router.delete("/users/{osm_id}", response_model=dict)
+@router.delete(
+    "/users/{osm_id}",
+    response_model=dict,
+    responses={**common_error_responses, **error_responses_with_examples},
+)
 async def delete_user(osm_id: int, user_data: AuthUser = Depends(admin_required)):
     """
     Deletes a user based on the given osm_id.
@@ -148,14 +181,19 @@ async def delete_user(osm_id: int, user_data: AuthUser = Depends(admin_required)
     - Dict[str, Any]: A dictionary containing the deleted user information.
 
     Raises:
-    - HTTPException: If the user with the given osm_id is not found.
+    - HTTPException 404: If the user with the given osm_id is not found.
+    - HTTPException 403: If the user is not an Admin.
     """
     auth = Users()
     return auth.delete_user(osm_id)
 
 
 # Get all users
-@router.get("/users/", response_model=list)
+@router.get(
+    "/users",
+    response_model=list,
+    responses={**common_error_responses, **error_responses_with_examples},
+)
 async def read_users(
     skip: int = 0, limit: int = 10, user_data: AuthUser = Depends(staff_required)
 ):
@@ -168,6 +206,9 @@ async def read_users(
 
     Returns:
     - List[Dict[str, Any]]: A list of dictionaries containing user information.
+
+    Raises:
+    - HTTPException 403: If the user is not a Staff.
     """
     auth = Users()
     return auth.read_users(skip, limit)

API/custom_exports.py

@@ -12,8 +12,7 @@
 
 router = APIRouter(prefix="/custom", tags=["Custom Exports"])
 
-
-@router.post("/snapshot/")
+@router.post("/snapshot")
 @limiter.limit(f"{RATE_LIMIT_PER_MIN}/minute")
 @version(1)
 async def process_custom_requests(

API/hdx.py

@@ -70,7 +70,7 @@ async def read_hdx_list(
     return hdx_list
 
 
-@router.get("/search/", response_model=List[dict])
+@router.get("/search", response_model=List[dict])
 @limiter.limit(f"{RATE_LIMIT_PER_MIN}/minute")
 @version(1)
 async def search_hdx(

API/main.py

@@ -75,7 +75,12 @@
 
     os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"
 
-app = FastAPI(title="Raw Data API ", swagger_ui_parameters={"syntaxHighlight": False})
+# Provides a brief overview of the API's functionality for documentation purposes.
+app = FastAPI(
+   title="Raw Data API",
+   description="Raw Data API is a set of high-performant APIs for transforming and exporting OpenStreetMap (OSM) data in different GIS file formats.",
+   swagger_ui_parameters={"syntaxHighlight": False}
+)
 app.include_router(auth_router)
 app.include_router(raw_data_router)
 app.include_router(tasks_router)

API/raw_data.py

@@ -26,6 +26,7 @@
 from fastapi import APIRouter, Body, Depends, HTTPException, Request
 from fastapi.responses import JSONResponse
 from fastapi_versioning import version
+from .auth.responses import common_error_responses, error_responses_with_examples
 
 from src.app import RawData
 from src.config import (
@@ -51,15 +52,23 @@
 redis_client = redis.StrictRedis.from_url(CELERY_BROKER_URL)
 
 
-@router.get("/status/", response_model=StatusResponse)
+@router.get(
+    "/status",
+    response_model=StatusResponse,
+    responses={**common_error_responses, **error_responses_with_examples},
+)
 @version(1)
 def check_database_last_updated():
     """Gives status about how recent the osm data is , it will give the last time that database was updated completely"""
     result = RawData().check_status()
     return {"last_updated": result}
 
 
-@router.post("/snapshot/", response_model=SnapshotResponse)
+@router.post(
+    "/snapshot",
+    response_model=SnapshotResponse,
+    responses={**common_error_responses, **error_responses_with_examples},
+)
 @limiter.limit(f"{export_rate_limit}/minute")
 @version(1)
 def get_osm_current_snapshot_as_file(
@@ -462,7 +471,10 @@ def get_osm_current_snapshot_as_file(
     )
 
 
-@router.post("/snapshot/plain/")
+@router.post(
+    "/snapshot/plain",
+    responses={**common_error_responses, **error_responses_with_examples},
+)
 @version(1)
 def get_osm_current_snapshot_as_plain_geojson(
     request: Request,
@@ -494,14 +506,18 @@ def get_osm_current_snapshot_as_plain_geojson(
     return result
 
 
-@router.get("/countries/")
+@router.get(
+    "/countries", responses={**common_error_responses, **error_responses_with_examples}
+)
 @version(1)
 def get_countries(q: str = ""):
     result = RawData().get_countries_list(q)
     return result
 
 
-@router.get("/osm_id/")
+@router.get(
+    "/osm_id", responses={**common_error_responses, **error_responses_with_examples}
+)
 @version(1)
 def get_osm_feature(osm_id: int):
     return RawData().get_osm_feature(osm_id)

API/s3.py

@@ -32,7 +32,7 @@
 paginator = s3.get_paginator("list_objects_v2")
 
 
-@router.get("/files/")
+@router.get("/files")
 @limiter.limit(f"{RATE_LIMIT_PER_MIN}/minute")
 @version(1)
 async def list_s3_files(

API/stats.py

@@ -11,7 +11,7 @@
 router = APIRouter(prefix="/stats", tags=["Stats"])
 
 
-@router.post("/polygon/")
+@router.post("/polygon")
 @limiter.limit(f"{POLYGON_STATISTICS_API_RATE_LIMIT}/minute")
 @version(1)
 async def get_polygon_stats(