Merge pull request #555 from VariantEffect/maintenance/bencap/542/cleanup-open-api-docs

Clean and Standardize OpenAPI Documentation

Author: bencap

src/mavedb/lib/authorization.py

@@ -2,7 +2,6 @@
 from typing import Optional
 
 from fastapi import Depends, HTTPException
-from starlette import status
 
 from mavedb.lib.authentication import UserData, get_current_user
 from mavedb.lib.logging.context import logging_context, save_to_logging_context
@@ -21,10 +20,7 @@ async def require_current_user(
 ) -> UserData:
     if user_data is None:
         logger.info(msg="Non-authenticated user attempted to access protected route.", extra=logging_context())
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Could not validate credentials",
-        )
+        raise HTTPException(status_code=401, detail="Could not validate credentials")
 
     return user_data
 
@@ -38,8 +34,7 @@ async def require_current_user_with_email(
             msg="User attempted to access email protected route without a valid email.", extra=logging_context()
         )
         raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail="There must be an email address associated with your account to use this feature.",
+            status_code=403, detail="There must be an email address associated with your account to use this feature."
         )
     return user_data
 
@@ -54,10 +49,7 @@ async def __call__(self, user_data: UserData = Depends(require_current_user)) ->
             logger.info(
                 msg="User attempted to access role protected route without a required role.", extra=logging_context()
             )
-            raise HTTPException(
-                status_code=status.HTTP_401_UNAUTHORIZED,
-                detail="You are not authorized to use this feature",
-            )
+            raise HTTPException(status_code=403, detail="You are not authorized to use this feature")
 
         return user_data
 
@@ -68,9 +60,6 @@ async def require_role(roles: list[UserRole], user_data: UserData = Depends(requ
         logger.info(
             msg="User attempted to access role protected route without a required role.", extra=logging_context()
         )
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="You are not authorized to use this feature",
-        )
+        raise HTTPException(status_code=403, detail="You are not authorized to use this feature")
 
     return user_data

src/mavedb/lib/taxonomies.py

@@ -66,6 +66,6 @@ async def search_NCBI_taxonomy(db: Session, search: str) -> Any:
             else:
                 raise HTTPException(status_code=404, detail=f"Taxonomy with search {search_text} not found in NCBI")
     else:
-        raise HTTPException(status_code=404, detail="Please enter valid searching words")
+        raise HTTPException(status_code=400, detail="Search text is required")
 
     return taxonomy_record

src/mavedb/routers/access_keys.py

@@ -8,6 +8,7 @@
 from fastapi import APIRouter, Depends
 from fastapi.encoders import jsonable_encoder
 from fastapi.exceptions import HTTPException
+from sqlalchemy import and_
 from sqlalchemy.orm import Session
 
 from mavedb import deps
@@ -17,15 +18,27 @@
 from mavedb.lib.logging.context import logging_context, save_to_logging_context
 from mavedb.models.access_key import AccessKey
 from mavedb.models.enums.user_role import UserRole
+from mavedb.routers.shared import ACCESS_CONTROL_ERROR_RESPONSES, PUBLIC_ERROR_RESPONSES, ROUTER_BASE_PREFIX
 from mavedb.view_models import access_key
 
+TAG_NAME = "Access Keys"
+
 router = APIRouter(
-    prefix="/api/v1",
-    tags=["access keys"],
-    responses={404: {"description": "Not found"}},
+    prefix=f"{ROUTER_BASE_PREFIX}",
+    tags=[TAG_NAME],
+    responses={**PUBLIC_ERROR_RESPONSES},
     route_class=LoggedRoute,
 )
 
+metadata = {
+    "name": TAG_NAME,
+    "description": "Manage API access keys for programmatic access to the MaveDB API.",
+    "externalDocs": {
+        "description": "Access Keys Documentation",
+        "url": "https://mavedb.org/docs/mavedb/accounts.html#api-access-tokens",
+    },
+}
+
 logger = logging.getLogger(__name__)
 
 
@@ -49,7 +62,8 @@ def generate_key_pair():
     "/users/me/access-keys",
     status_code=200,
     response_model=list[access_key.AccessKey],
-    responses={404: {}, 500: {}},
+    responses={**ACCESS_CONTROL_ERROR_RESPONSES},
+    summary="List my access keys",
 )
 def list_my_access_keys(*, user_data: UserData = Depends(require_current_user)) -> Any:
     """
@@ -62,7 +76,8 @@ def list_my_access_keys(*, user_data: UserData = Depends(require_current_user))
     "/users/me/access-keys",
     status_code=200,
     response_model=access_key.NewAccessKey,
-    responses={404: {}, 500: {}},
+    responses={**ACCESS_CONTROL_ERROR_RESPONSES},
+    summary="Create a new access key for myself",
 )
 def create_my_access_key(
     *,
@@ -88,7 +103,8 @@ def create_my_access_key(
     "/users/me/access-keys/{role}",
     status_code=200,
     response_model=access_key.NewAccessKey,
-    responses={404: {}, 500: {}},
+    responses={**ACCESS_CONTROL_ERROR_RESPONSES},
+    summary="Create a new access key for myself with a specified role",
 )
 async def create_my_access_key_with_role(
     *,
@@ -125,7 +141,12 @@ async def create_my_access_key_with_role(
     return response_item
 
 
-@router.delete("/users/me/access-keys/{key_id}", status_code=200, responses={404: {}, 500: {}})
+@router.delete(
+    "/users/me/access-keys/{key_id}",
+    status_code=200,
+    responses={**ACCESS_CONTROL_ERROR_RESPONSES},
+    summary="Delete one of my access keys",
+)
 def delete_my_access_key(
     *,
     key_id: str,
@@ -135,8 +156,20 @@ def delete_my_access_key(
     """
     Delete one of the current user's access keys.
     """
-    item = db.query(AccessKey).filter(AccessKey.key_id == key_id).one_or_none()
-    if item and item.user.id == user_data.user.id:
-        db.delete(item)
-        db.commit()
-        logger.debug(msg="Successfully deleted provided API key.", extra=logging_context())
+    item = (
+        db.query(AccessKey)
+        .filter(and_(AccessKey.key_id == key_id, AccessKey.user_id == user_data.user.id))
+        .one_or_none()
+    )
+
+    if not item:
+        logger.warning(
+            msg="Could not delete API key; Provided key ID does not exist and/or does not belong to the current user.",
+            extra=logging_context(),
+        )
+        # Never acknowledge the existence of an access key that doesn't belong to the user.
+        raise HTTPException(status_code=404, detail=f"Access key with ID {key_id} not found.")
+
+    db.delete(item)
+    db.commit()
+    logger.debug(msg="Successfully deleted provided API key.", extra=logging_context())

src/mavedb/routers/api_information.py

@@ -3,15 +3,27 @@
 from fastapi import APIRouter
 
 from mavedb import __project__, __version__
+from mavedb.routers.shared import PUBLIC_ERROR_RESPONSES, ROUTER_BASE_PREFIX
 from mavedb.view_models import api_version
 
-router = APIRouter(prefix="/api/v1/api", tags=["api information"], responses={404: {"description": "Not found"}})
+TAG_NAME = "API Information"
 
+router = APIRouter(
+    prefix=f"{ROUTER_BASE_PREFIX}/api",
+    tags=[TAG_NAME],
+    responses={**PUBLIC_ERROR_RESPONSES},
+)
 
-@router.get("/version", status_code=200, response_model=api_version.ApiVersion, responses={404: {}})
+metadata = {
+    "name": TAG_NAME,
+    "description": "Retrieve information about the MaveDB API.",
+}
+
+
+@router.get("/version", status_code=200, response_model=api_version.ApiVersion, summary="Show API version")
 def show_version() -> Any:
     """
-    Describe the API version.
+    Describe the API version and project.
     """
 
     return api_version.ApiVersion(name=__project__, version=__version__)