Enhance/raw-data-api

API/auth/routers.py

@@ -10,7 +10,20 @@
 router = APIRouter(prefix="/auth", tags=["Auth"])
 
 
-@router.get("/login/")
+class ErrorMessage(BaseModel):
+    detail: str
+
+
+responses = {
+    403: {"model": ErrorMessage,
+          "content": {"application/json": {"example": {"detail": "OSM Authentication failed"}}}},
+    500: {"model": ErrorMessage,
+          "content": {"application/json": {"example": {"detail": "Internal Server Error"}}}},
+}
+
+
+@router.get("/login", responses={500: {"model": ErrorMessage},
+                                  200: {"content": {"application/json": {"example": {"loginUrl": ""}}}}})
 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.
@@ -21,11 +34,12 @@ def login_url(request: Request):
     - login_url (dict) - URL to authorize user to the application via. Openstreetmap
         OAuth2 with client_id, redirect_uri, and permission scope as query_string parameters
     """
+
     login_url = osm_auth.login()
     return login_url
 
 
-@router.get("/callback/")
+@router.get("/callback", responses={500: {"model": ErrorMessage}})
 def callback(request: Request):
     """Performs token exchange between OpenStreetMap and Raw Data API
 
@@ -37,34 +51,38 @@ def callback(request: Request):
     Returns:
     - access_token (string)
     """
-    access_token = osm_auth.callback(str(request.url))
 
-    return access_token
+    access_token = osm_auth.callback(str(request.url))
+    return access_token  
 
 
-@router.get("/me/", response_model=AuthUser)
+@router.get("/me", response_model=AuthUser, responses={**responses})
 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 .
 
     Parameters:None
 
-    Returns: user_data
+    Returns: user_data\n
             User Role :
                 ADMIN = 1
                 STAFF = 2
                 GUEST = 3
+
+    Raises:
+    - HTTPException 403: Due to authentication error(Wrong access token).
+    - HTTPException 500: Internal server error.
     """
     return user_data
 
 
 class User(BaseModel):
     osm_id: int
     role: int
-
+ 
 
 # Create user
-@router.post("/users/", response_model=dict)
+@router.post("/users", response_model=dict, responses={**responses})
 async def create_user(params: User, user_data: AuthUser = Depends(admin_required)):
     """
     Creates a new user and returns the user's information.
@@ -80,14 +98,15 @@ async def create_user(params: User, user_data: AuthUser = Depends(admin_required
     - Dict[str, Any]: A dictionary containing the osm_id of the newly created user.
 
     Raises:
-    - HTTPException: If the user creation fails.
+    - HTTPException 403: If the user creation fails due to insufficient permission.
+    - HTTPException 500: If the user creation fails due to internal server error.
     """
     auth = Users()
     return auth.create_user(params.osm_id, params.role)
 
 
 # Read user by osm_id
-@router.get("/users/{osm_id}", response_model=dict)
+@router.get("/users/{osm_id}", response_model=dict, responses={**responses, 404:{"model": ErrorMessage}})
 async def read_user(osm_id: int, user_data: AuthUser = Depends(staff_required)):
     """
     Retrieves user information based on the given osm_id.
@@ -103,15 +122,17 @@ 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 403: If the user has insufficient permission.
+    - HTTPException 404: If the user with the given osm_id is not found.
+    - HTTPException 500: If it fails due to internal server error.
     """
     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={**responses, 404:{"model": ErrorMessage}})
 async def update_user(
     osm_id: int, update_data: User, user_data: AuthUser = Depends(admin_required)
 ):
@@ -129,14 +150,16 @@ 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 has insufficient permission.
+    - HTTPException 404: If the user with the given osm_id is not found.
+    - HTTPException 500: If it fails due to internal server error.
     """
     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={**responses, 404:{"model": ErrorMessage}})
 async def delete_user(osm_id: int, user_data: AuthUser = Depends(admin_required)):
     """
     Deletes a user based on the given osm_id.
@@ -148,14 +171,16 @@ 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 403: If the user has insufficient permission.
+    - HTTPException 404: If the user with the given osm_id is not found.
+    - HTTPException 500: If it fails due to internal server error.
     """
     auth = Users()
     return auth.delete_user(osm_id)
 
 
 # Get all users
-@router.get("/users/", response_model=list)
+@router.get("/users", response_model=list, responses={**responses})
 async def read_users(
     skip: int = 0, limit: int = 10, user_data: AuthUser = Depends(staff_required)
 ):
@@ -168,6 +193,10 @@ async def read_users(
 
     Returns:
     - List[Dict[str, Any]]: A list of dictionaries containing user information.
+
+    Raises:
+    - HTTPException 403: If it fails due to insufficient permission.
+    - HTTPException 500: If it fails due to internal server error.
     """
     auth = Users()
     return auth.read_users(skip, limit)

API/main.py

@@ -75,7 +75,11 @@
 
     os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"
 
-app = FastAPI(title="Raw Data API ", swagger_ui_parameters={"syntaxHighlight": False})
+app = FastAPI(title="Raw Data API ", 
+            description="""The Raw Data API allows you to transform 
+              and export 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)