diff --git a/API/auth/__init__.py b/API/auth/__init__.py index 0ff71d79..6428d559 100644 --- a/API/auth/__init__.py +++ b/API/auth/__init__.py @@ -1,6 +1,7 @@ from enum import Enum from typing import Union +from fastapi.security import APIKeyHeader from fastapi import Depends, Header, HTTPException from osm_login_python.core import Auth from pydantic import BaseModel, Field @@ -9,6 +10,11 @@ from src.config import get_oauth_credentials +Raw_Data_Access_Token = APIKeyHeader( + name="Access_Token", description="Access Token to Authorize User" +) + + class UserRole(Enum): ADMIN = 1 STAFF = 2 @@ -21,6 +27,16 @@ class AuthUser(BaseModel): img_url: Union[str, None] role: UserRole = Field(default=UserRole.GUEST.value) + class Config: + json_schema_extra = { + "example": { + "id": "123", + "username": "HOT Team", + "img_url": "https://hotteamimage.com", + "role": UserRole.GUEST.value, + } + } + osm_auth = Auth(*get_oauth_credentials()) @@ -43,11 +59,15 @@ def get_osm_auth_user(access_token): return user -def login_required(access_token: str = Header(...)): +def login_required(access_token: str = Depends(Raw_Data_Access_Token)): return get_osm_auth_user(access_token) -def get_optional_user(access_token: str = Header(default=None)) -> AuthUser: +def get_optional_user( + access_token: str = Header( + default=None, description="Access Token to Authorize User" + ) +) -> AuthUser: if access_token: return get_osm_auth_user(access_token) else: @@ -58,7 +78,7 @@ def get_optional_user(access_token: str = Header(default=None)) -> AuthUser: def admin_required(user: AuthUser = Depends(login_required)): db_user = get_user_from_db(user.id) if not db_user["role"] is UserRole.ADMIN.value: - raise HTTPException(status_code=403, detail="User is not an admin") + raise HTTPException(status_code=403, detail=[{"msg": "User is not an admin"}]) return user @@ -70,5 +90,5 @@ def staff_required(user: AuthUser = Depends(login_required)): db_user["role"] is UserRole.STAFF.value or db_user["role"] is UserRole.ADMIN.value ): - raise HTTPException(status_code=403, detail="User is not a staff") + raise HTTPException(status_code=403, detail=[{"msg": "User is not a staff"}]) return user diff --git a/API/auth/routers.py b/API/auth/routers.py index 438a28e4..817125c6 100644 --- a/API/auth/routers.py +++ b/API/auth/routers.py @@ -1,16 +1,32 @@ import json -from fastapi import APIRouter, Depends, Request +from fastapi import APIRouter, Depends, Request, Query, Path from pydantic import BaseModel from src.app import Users +from src.validation.models import ErrorMessage, common_responses from . import AuthUser, admin_required, login_required, osm_auth, staff_required router = APIRouter(prefix="/auth", tags=["Auth"]) -@router.get("/login/") +@router.get( + "/login", + responses={ + 200: { + "description": "A Login URL", + "content": { + "application/json": { + "example": { + "login_url": "https://www.openstreetmap.org/oauth2/authorize/" + } + } + }, + }, + 500: {"model": ErrorMessage}, + }, +) 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 +41,7 @@ def login_url(request: Request): 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 @@ -42,18 +58,27 @@ def callback(request: Request): return access_token -@router.get("/me/", response_model=AuthUser) +@router.get( + "/me", + response_model=AuthUser, + responses={**common_responses}, + response_description="User Information", +) 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 @@ -62,9 +87,19 @@ class User(BaseModel): osm_id: int role: int + class Config: + json_schema_extra = {"example": {"osm_id": 123, "role": 1}} + # Create user -@router.post("/users/", response_model=dict) +@router.post( + "/users", + response_model=dict, + responses={ + **common_responses, + "200": {"content": {"application/json": {"example": {"osm_id": 123}}}}, + }, +) async def create_user(params: User, user_data: AuthUser = Depends(admin_required)): """ Creates a new user and returns the user's information. @@ -80,15 +115,26 @@ 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) -async def read_user(osm_id: int, user_data: AuthUser = Depends(staff_required)): +@router.get( + "/users/{osm_id}", + responses={ + **common_responses, + "200": {"content": {"application/json": {"example": {"osm_id": 1, "role": 2}}}}, + "404": {"model": ErrorMessage}, + }, +) +async def read_user( + osm_id: int = Path(description="The OSM ID of the User to Retrieve"), + user_data: AuthUser = Depends(staff_required), +): """ Retrieves user information based on the given osm_id. User Role : @@ -103,7 +149,9 @@ 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() @@ -111,9 +159,18 @@ async def read_user(osm_id: int, user_data: AuthUser = Depends(staff_required)): # Update user by osm_id -@router.put("/users/{osm_id}", response_model=dict) +@router.put( + "/users/{osm_id}", + responses={ + **common_responses, + "200": {"content": {"application/json": {"example": {"osm_id": 1, "role": 1}}}}, + "404": {"model": ErrorMessage}, + }, +) async def update_user( - osm_id: int, update_data: User, user_data: AuthUser = Depends(admin_required) + update_data: User, + user_data: AuthUser = Depends(admin_required), + osm_id: int = Path(description="The OSM ID of the User to Update"), ): """ Updates user information based on the given osm_id. @@ -129,15 +186,27 @@ 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) -async def delete_user(osm_id: int, user_data: AuthUser = Depends(admin_required)): +@router.delete( + "/users/{osm_id}", + responses={ + **common_responses, + "200": {"content": {"application/json": {"example": {"osm_id": 1, "role": 1}}}}, + "404": {"model": ErrorMessage}, + }, +) +async def delete_user( + user_data: AuthUser = Depends(admin_required), + osm_id: int = Path(description="The OSM ID of the User to Delete"), +): """ Deletes a user based on the given osm_id. @@ -148,16 +217,29 @@ 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={ + **common_responses, + "200": { + "content": {"application/json": {"example": [{"osm_id": 1, "role": 2}]}} + }, + }, +) async def read_users( - skip: int = 0, limit: int = 10, user_data: AuthUser = Depends(staff_required) + skip: int = Query(0, description="The Number of Users to Skip"), + limit: int = Query(10, description="The Maximum Number of Users to Retrieve"), + user_data: AuthUser = Depends(staff_required), ): """ Retrieves a list of users with optional pagination. @@ -168,6 +250,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) diff --git a/API/main.py b/API/main.py index f887895a..56d775a6 100644 --- a/API/main.py +++ b/API/main.py @@ -75,7 +75,12 @@ 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) diff --git a/API/raw_data.py b/API/raw_data.py index 46c8e068..f1976e1f 100644 --- a/API/raw_data.py +++ b/API/raw_data.py @@ -23,7 +23,7 @@ import redis from area import area -from fastapi import APIRouter, Body, Depends, HTTPException, Request +from fastapi import APIRouter, Body, Depends, HTTPException, Request, Path, Query from fastapi.responses import JSONResponse from fastapi_versioning import version @@ -41,6 +41,8 @@ RawDataCurrentParamsBase, SnapshotResponse, StatusResponse, + ErrorMessage, + common_responses, ) from .api_worker import process_raw_data @@ -51,15 +53,26 @@ redis_client = redis.StrictRedis.from_url(CELERY_BROKER_URL) -@router.get("/status/", response_model=StatusResponse) +@router.get( + "/status", response_model=StatusResponse, responses={"500": {"model": ErrorMessage}} +) @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""" + """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_responses, + 404: {"model": ErrorMessage}, + 429: {"model": ErrorMessage}, + }, +) @limiter.limit(f"{export_rate_limit}/minute") @version(1) def get_osm_current_snapshot_as_file( @@ -411,7 +424,7 @@ def get_osm_current_snapshot_as_file( status_code=403, detail=[ { - "msg": "Insufficient Permission to use folder structure exports , Remove / from filename or get access" + "msg": "Insufficient Permission to use folder structure exports, Remove / from filename or get access" } ], ) @@ -462,7 +475,9 @@ def get_osm_current_snapshot_as_file( ) -@router.post("/snapshot/plain/") +@router.post( + "/snapshot/plain", responses={**common_responses, 404: {"model": ErrorMessage}} +) @version(1) def get_osm_current_snapshot_as_plain_geojson( request: Request, @@ -473,7 +488,7 @@ def get_osm_current_snapshot_as_plain_geojson( Args: request (Request): _description_ - params (RawDataCurrentParamsBase): Same as /snapshot excpet multiple output format options and configurations + params (RawDataCurrentParamsBase): Same as /snapshot except multiple output format options and configurations Returns: Featurecollection: Geojson @@ -494,14 +509,39 @@ def get_osm_current_snapshot_as_plain_geojson( return result -@router.get("/countries/") +@router.get("/countries", responses={"500": {"model": ErrorMessage}}) @version(1) -def get_countries(q: str = ""): +def get_countries( + q: str = Query("", description="Query parameter for filtering countries") +): + """ + Gets Countries list from the database + + Args: + q (str): query parameter for filtering countries + + Returns: + featurecollection: geojson of country + """ + result = RawData().get_countries_list(q) return result -@router.get("/osm_id/") +@router.get( + "/osm_id", + responses={"404": {"model": ErrorMessage}, "500": {"model": ErrorMessage}}, +) @version(1) -def get_osm_feature(osm_id: int): +def get_osm_feature(osm_id: int = Path(description="The OSM ID of feature")): + """ + Gets geometry of osm_id in geojson + + Args: + osm_id (int): osm_id of feature + + Returns: + featurecollection: Geojson + """ + return RawData().get_osm_feature(osm_id) diff --git a/src/validation/models.py b/src/validation/models.py index 0e3a3a63..eb477cc8 100644 --- a/src/validation/models.py +++ b/src/validation/models.py @@ -244,8 +244,8 @@ class SnapshotResponse(BaseModel): class Config: json_schema_extra = { "example": { - "task_id": "aa539af6-83d4-4aa3-879e-abf14fffa03f", - "track_link": "/tasks/status/aa539af6-83d4-4aa3-879e-abf14fffa03f/", + "taskId": "aa539af6-83d4-4aa3-879e-abf14fffa03f", + "trackLink": "/tasks/status/aa539af6-83d4-4aa3-879e-abf14fffa03f/", } } @@ -288,6 +288,67 @@ class Config: json_schema_extra = {"example": {"lastUpdated": "2022-06-27 19:59:24+05:45"}} +class ErrorDetail(BaseModel): + msg: str + + +class ErrorMessage(BaseModel): + detail: List[ErrorDetail] + + +common_responses = { + 401: { + "model": ErrorMessage, + "content": { + "application/json": { + "example": {"detail": [{"msg": "OSM Authentication failed"}]} + } + }, + }, + 403: { + "model": ErrorMessage, + "content": { + "application/json": { + "example": {"detail": [{"msg": "OSM Authentication failed"}]} + } + }, + }, + 500: {"model": ErrorMessage}, +} + +stats_response = { + "200": { + "content": { + "application/json": { + "example": { + "summary": {"buildings": "", "roads": ""}, + "raw": { + "population": 0, + "populatedAreaKm2": 0, + "averageEditTime": 0, + "lastEditTime": 0, + "osmUsersCount": 0, + "osmBuildingCompletenessPercentage": 0, + "osmRoadsCompletenessPercentage": 0, + "osmBuildingsCount": 0, + "osmHighwayLengthKm": 0, + "aiBuildingsCountEstimation": 0, + "aiRoadCountEstimationKm": 0, + "buildingCount6Months": 0, + "highwayLength6MonthsKm": 0, + }, + "meta": { + "indicators": "https://github.com/hotosm/raw-data-api/tree/develop/docs/src/stats/indicators.md", + "metrics": "https://github.com/hotosm/raw-data-api/tree/develop/docs/src/stats/metrics.md", + }, + } + } + } + }, + "500": {"model": ErrorMessage}, +} + + class StatsRequestParams(BaseModel, GeometryValidatorMixin): iso3: Optional[str] = Field( default=None, @@ -296,22 +357,22 @@ class StatsRequestParams(BaseModel, GeometryValidatorMixin): max_length=3, example="NPL", ) - geometry: Optional[ - Union[Polygon, MultiPolygon, Feature, FeatureCollection] - ] = Field( - default=None, - example={ - "type": "Polygon", - "coordinates": [ - [ - [83.96919250488281, 28.194446860487773], - [83.99751663208006, 28.194446860487773], - [83.99751663208006, 28.214869548073377], - [83.96919250488281, 28.214869548073377], - [83.96919250488281, 28.194446860487773], - ] - ], - }, + geometry: Optional[Union[Polygon, MultiPolygon, Feature, FeatureCollection]] = ( + Field( + default=None, + example={ + "type": "Polygon", + "coordinates": [ + [ + [83.96919250488281, 28.194446860487773], + [83.99751663208006, 28.194446860487773], + [83.99751663208006, 28.214869548073377], + [83.96919250488281, 28.214869548073377], + [83.96919250488281, 28.194446860487773], + ] + ], + }, + ) ) @validator("geometry", pre=True, always=True) @@ -608,22 +669,22 @@ class DynamicCategoriesModel(BaseModel, GeometryValidatorMixin): } ], ) - geometry: Optional[ - Union[Polygon, MultiPolygon, Feature, FeatureCollection] - ] = Field( - default=None, - example={ - "type": "Polygon", - "coordinates": [ - [ - [83.96919250488281, 28.194446860487773], - [83.99751663208006, 28.194446860487773], - [83.99751663208006, 28.214869548073377], - [83.96919250488281, 28.214869548073377], - [83.96919250488281, 28.194446860487773], - ] - ], - }, + geometry: Optional[Union[Polygon, MultiPolygon, Feature, FeatureCollection]] = ( + Field( + default=None, + example={ + "type": "Polygon", + "coordinates": [ + [ + [83.96919250488281, 28.194446860487773], + [83.99751663208006, 28.194446860487773], + [83.99751663208006, 28.214869548073377], + [83.96919250488281, 28.214869548073377], + [83.96919250488281, 28.194446860487773], + ] + ], + }, + ) ) @validator("geometry", pre=True, always=True)