refactor: operation_id generation across routers

our web client has a ticket where we require the operation_id of the openapi spec to be human
readable, this is inline with cameCasing and snake_casing depending on the server or client
anomaly/lab-web-client#6

the attempt is to greatly improve code readability which in turn makes documentation a lot
more readable. initially we were assigning the operation_id manually but have nice moved
to using what's references in the fastapi docs
https://bit.ly/3rXeAvH

this does imply that the function names have to well written by developers

Author: devraj

src/labs/api.py

@@ -12,8 +12,9 @@
 """
 from . import __title__, __version__
 
-from fastapi import FastAPI, Request, Depends, status, WebSocket
+from fastapi import FastAPI, Request, status, WebSocket
 from fastapi.responses import JSONResponse
+from fastapi.routing import APIRoute
 
 from .routers import router_auth, router_ext
 
@@ -31,33 +32,34 @@
 """A FastAPI application that serves handlers
 """
 app = FastAPI(
-    title=__title__,
-    version=__version__,
-    description=api_description,
-    docs_url="/docs",
-    terms_of_service="https://github.com/anomaly/labs",
-    contact={
-      "name": "Anomaly Software",
-      "url": "https://github.com/anomaly/labs",
-      "email": "[email protected]"
-    },
-    license_info={
-      "name": "Apache 2.0",
-      "url": "https://www.apache.org/licenses/LICENSE-2.0"
-    },
-    openapi_tags=[
-      {
-        "name": "auth",
-        "description": "Authentication related endpoints"
-      }
-    ]
-    )
+  title=__title__,
+  version=__version__,
+  description=api_description,
+  docs_url="/docs",
+  terms_of_service="https://github.com/anomaly/labs",
+  contact={
+    "name": "Anomaly Software",
+    "url": "https://github.com/anomaly/labs",
+    "email": "[email protected]"
+  },
+  license_info={
+    "name": "Apache 2.0",
+    "url": "https://www.apache.org/licenses/LICENSE-2.0"
+  },
+  openapi_tags=[
+    {
+      "name": "auth",
+      "description": "Authentication related endpoints"
+    }
+  ]
+)
 
 # Additional routers of the application described in the routers package
 app.include_router(router_auth, prefix="/auth")
 app.include_router(router_ext, prefix="/ext")
 
 
+
 @app.get("/")
 async def root(request: Request):
   """Placeholder for the root endpoint
@@ -78,4 +80,24 @@ async def websocket_endpoint(websocket: WebSocket):
     await websocket.send_text(f"Message text was: {data}")
 
 # Hook up any events worth responding to
-# https://fastapi.tiangolo.com/advanced/events/
+# https://fastapi.tiangolo.com/advanced/events/
+
+# With a little help from FastAPI docs
+# https://bit.ly/3rXeAvH
+#
+# Globally use the path name as the operation id thus
+# making things a lot more readable, note that this requires
+# you name your functions really well.
+def use_route_names_as_operation_ids(app: FastAPI) -> None:
+  """
+  Simplify operation IDs so that generated API clients have simpler function
+  names.
+
+  Should be called only after all routes have been added.
+  """
+  for route in app.routes:
+    if isinstance(route, APIRoute):
+      route.operation_id = route.name
+
+
+use_route_names_as_operation_ids(app)

src/labs/routers/auth/__init__.py

@@ -49,6 +49,7 @@ async def login_user(request: PasswordLoginRequest,
                       token_type="Bearer",
                       expires_in=100)
 
+
 @router.post("/refresh",
   summary=""" Provides an endpoint for refreshing the JWT token""",
   response_model=AuthResponse,
@@ -66,11 +67,15 @@ async def refresh_jwt_token(request: Request,
   operation_id="logout_user"
 )
 async def logout_user(session: AsyncSession = Depends(session_context)):
+  """ Ends a users session
+  
+  """
   return {}
 
 @router.get("/me", response_model=UserRequest)
 async def get_me(request: Request,
-  session: AsyncSession = Depends(session_context)):
+  session: AsyncSession = Depends(session_context)
+):
   """Get the currently logged in user or myself
 
   This endpoint will return the currently logged in user or raise

src/labs/routers/auth/create.py

@@ -19,7 +19,8 @@
   operation_id="signup_user",
 )
 async def signup_user(request: SignupRequest, 
-  session: AsyncSession = Depends(get_async_session)):
+  session: AsyncSession = Depends(get_async_session)
+):
   # Try and get a user by email
   user = await User.get_by_email(session, request.email)
   if user:
@@ -34,7 +35,7 @@ async def signup_user(request: SignupRequest,
   "/verify",
   operation_id="verify_user",
 )
-async def verify_user_account(request: Request):
+async def verify_user(request: Request):
     """Verify an account
     """
     verification_email.delay()

src/labs/routers/auth/otp.py

@@ -16,10 +16,10 @@
 
 @router.post("/initiate/email",
   response_model=OTPTriggerResponse,
-  operation_id="initiate_otp_via_email",
 )
-async def initiate_otp_request(request: OTPTriggerEmailRequest, 
-  session: AsyncSession = Depends(get_async_session)):
+async def initiate_otp_email(request: OTPTriggerEmailRequest, 
+  session: AsyncSession = Depends(get_async_session)
+):
   """ Attempt to authenticate a user and issue JWT token
 
     The user has provided us their email address and we will
@@ -42,10 +42,10 @@ async def initiate_otp_request(request: OTPTriggerEmailRequest,
 
 @router.post("/initiate/sms",
   response_model=OTPTriggerResponse,
-  operation_id="initiate_otp_via_sms"
 )
-async def initiate_otp_request(request: OTPTriggerSMSRequest, 
-  session: AsyncSession = Depends(get_async_session)):
+async def initiate_otp_sms(request: OTPTriggerSMSRequest, 
+  session: AsyncSession = Depends(get_async_session)
+):
   """ Attempt to authenticate a user and issue JWT token
 
     The user has provided a mobile number and we will text them
@@ -66,7 +66,8 @@ async def initiate_otp_request(request: OTPTriggerSMSRequest,
 
 @router.post("/verify")
 async def verify_otp(request: OTPVerifyRequest, 
-  session: AsyncSession = Depends(get_async_session)):
+  session: AsyncSession = Depends(get_async_session)
+):
   """ Attempt to authenticate a user and issue JWT token
   
   """

src/labs/routers/ext/__init__.py

@@ -19,7 +19,7 @@ async def echo(request: Request):
     return {"message": "Hello, world!"}
 
 @router.get("/healthcheck")
-async def perform_healthcheck(request: Request):
+async def get_health(request: Request):
     """Check the health of the server.
 
     Purpose of this endpoint is to check the health of the server.
@@ -30,7 +30,9 @@ async def perform_healthcheck(request: Request):
 
 
 @router.get("/log")
-async def write_to_logger(request: Request, session: AsyncSession = Depends(session_context)):
+async def test_logger(request: Request,
+    session: AsyncSession = Depends(session_context)
+):
     """Log a message.
 
     Purpose of this endpoint is to log a message to the logger.

src/labs/routers/stripe/__init__.py

@@ -33,7 +33,7 @@
 # Note that include_in_schema=False and this will not appear
 # in the OpenAPI documentation
 @router.post("/webhook", include_in_schema=False)
-async def process_webhook(
+async def stripe_webhook(
   request: Request,
   background_tasks: BackgroundTasks,
   STRIPE_SIGNATURE: str = Header(default=None),