chore: add return type annotations of APIs

given that FastAPI `response_model` now support return type annotation

see more details at:
1. tiangolo/fastapi#101
2. tiangolo/fastapi#1436

api/routers/contest_records.py

@@ -1,5 +1,5 @@
 import asyncio
-from typing import Optional
+from typing import List, Optional
 
 from fastapi import APIRouter, Request
 from loguru import logger
@@ -19,7 +19,16 @@ async def contest_records_count(
     request: Request,
     contest_name: str,
     archived: Optional[bool] = False,
-):
+) -> int:
+    """
+    Count records of a given contest.
+    By default, count predicted contests only.
+    Count archived contests when setting `archived = True` explicitly.
+    :param request:
+    :param contest_name:
+    :param archived:
+    :return:
+    """
     logger.info(f"{request.client=}")
     await check_contest_name(contest_name)
     if not archived:
@@ -42,7 +51,18 @@ async def contest_records(
     archived: Optional[bool] = False,
     skip: Optional[NonNegativeInt] = 0,
     limit: Optional[conint(ge=1, le=100)] = 25,
-):
+) -> List[ContestRecordPredict | ContestRecordArchive]:
+    """
+    Query all records of a given contest.
+    By default, query predicted contests only.
+    Query archived contests when setting `archived = True` explicitly.
+    :param request:
+    :param contest_name:
+    :param archived:
+    :param skip:
+    :param limit:
+    :return:
+    """
     logger.info(f"{request.client=}")
     await check_contest_name(contest_name)
     if not archived:
@@ -76,7 +96,17 @@ async def contest_records_user(
     contest_name: str,
     username: str,
     archived: Optional[bool] = False,
-):
+) -> List[ContestRecordPredict | ContestRecordArchive]:
+    """
+    Query records of a given contest by username.
+    By default, query predicted contests only.
+    Query archived contests when setting `archived = True` explicitly.
+    :param request:
+    :param contest_name:
+    :param username:
+    :param archived:
+    :return:
+    """
     logger.info(f"{request.client=}")
     await check_contest_name(contest_name)
     if not archived:
@@ -109,7 +139,7 @@ class ResultOfContestRecordPredict(BaseModel):
 async def predicted_rating(
     request: Request,
     query: RequestOfContestRecords,
-):
+) -> List[Optional[ResultOfContestRecordPredict]]:
     """
     Query multiple predicted records in a contest.
     :param request:
@@ -143,7 +173,13 @@ class ResultOfRealTimeRank(BaseModel):
 async def real_time_rank(
     request: Request,
     query: RequestOfRealTimeRank,
-):
+) -> ResultOfRealTimeRank:
+    """
+    Query user's realtime rank list of a given contest.
+    :param request:
+    :param query:
+    :return:
+    """
     logger.info(f"{request.client=}")
     await check_contest_name(query.contest_name)
     return await ContestRecordArchive.find_one(

api/routers/contests.py

@@ -1,5 +1,5 @@
 from datetime import datetime
-from typing import Optional
+from typing import List, Optional
 
 from fastapi import APIRouter, Request
 from loguru import logger
@@ -14,7 +14,10 @@
 
 
 @router.get("/count")
-async def contests_count(request: Request, archived: Optional[bool] = False):
+async def contests_count(
+    request: Request,
+    archived: Optional[bool] = False,
+) -> int:
     """
     Count total contests in database.
     By default, count predicted contests only.
@@ -39,11 +42,11 @@ async def contests(
     archived: Optional[bool] = False,
     skip: Optional[NonNegativeInt] = 0,
     limit: Optional[conint(ge=1, le=25)] = 10,
-):
+) -> List[Contest]:
     """
-    Query total contests in database.
+    Query contests in database.
     By default, Query predicted contests only.
-    Query all archived contests when setting `archived = True` explicitly.
+    Query archived contests when setting `archived = True` explicitly.
     :param request:
     :param archived:
     :param skip:

api/routers/questions.py

@@ -1,5 +1,5 @@
 import asyncio
-from typing import Optional
+from typing import List, Optional
 
 from fastapi import APIRouter, HTTPException, Request
 from loguru import logger
@@ -23,7 +23,14 @@ class RequestOfQuestions(BaseModel):
 async def questions(
     request: Request,
     query: RequestOfQuestions,
-):
+) -> List[Question]:
+    """
+    Query questions for a given contest.
+    Questions number must between 1 and 4 inclusively.
+    :param request:
+    :param query:
+    :return:
+    """
     logger.info(f"{request.client=}")
     if not (bool(query.contest_name) ^ bool(query.question_id_list)):
         msg = "contest_name OR question_id_list must be given!"