Merge pull request #75 from adithyasunil04/api_docs

docs: added documentation to all API endpoint routes so far

Author: KreativeThinker

src/pwncore/models/ctf.py

@@ -5,7 +5,7 @@
 from tortoise.models import Model
 from tortoise import fields
 from tortoise.contrib.pydantic import pydantic_model_creator
-
+from pydantic import BaseModel
 from pwncore.models.user import Team
 
 __all__ = (
@@ -19,6 +19,8 @@
     "BaseProblem",
 )
 
+class Flag(BaseModel):
+    flag: str
 
 class BaseProblem(Model):
     name = fields.TextField()

src/pwncore/models/responseModels/CTF_StatusResponse.py

@@ -0,0 +1,41 @@
+from pydantic import BaseModel
+from typing import List, Optional
+
+class CTF_ErrorResponse(BaseModel):
+    """
+    Error response for CTF operations
+    - 404: ctf_not_found : 2
+    - 403: hint_limit_reached : 9
+    - 412: Insufficient coins : 22
+    - 406: container_already_running : 7
+    - 429: container_limit_reached : 8
+    - 500: db_error : 0
+    """
+    msg_code: int
+
+class ContainerStartResponse(BaseModel):
+    """
+    Response for container start operation
+    msg_codes: 
+    - (success) container_start : 3
+    """
+    msg_code: int
+    ports: Optional[List[int]] = None
+    ctf_id: Optional[int] = None
+
+class ContainerStopResponse(BaseModel):
+    """
+    Response for container stop operations
+    - (success) container_stop : 4
+    - (fail) 
+        - 404: ctf_not_found : 2
+        - 400: container_not_found  : 6
+        - 500: db_error : 0 
+    """
+    msg_code: int
+
+class ContainerPortsResponse(BaseModel):
+    """
+    Response for all open ports of containers
+    """
+    ports: dict[int, list[int]]

src/pwncore/models/responseModels/adminResponse.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel
+from typing import Optional
+
+class AdminBaseResponse(BaseModel):
+    """
+    Generic response for admin operations
+    """
+    success: bool
+    message: Optional[str] = None

src/pwncore/models/responseModels/ctf_ContainerStatusResponse.py

@@ -0,0 +1,32 @@
+from pydantic import BaseModel
+from typing import List, Optional
+
+class CTF_ErrorResponse(BaseModel):
+    """
+    Generic error response
+    msg_code: 0 (db_error), 2 (ctf_not_found)
+    """
+    msg_code: int
+
+class ContainerStartResponse(BaseModel):
+    """
+    Response for container start operation
+    msg_code: 3 (success), 7 (already running), 8 (limit reached), 0 (db_error)
+    """
+    msg_code: int
+    ports: Optional[List[int]] = None
+    ctf_id: Optional[int] = None
+
+class ContainerStopResponse(BaseModel):
+    """
+    Response for container stop operations
+    msg_code: 4 (stop success), 5 (stopall success), 6 (not found), 0 (db_error)
+    """
+    msg_code: int
+
+class ContainerPortsResponse(BaseModel):
+    """
+    Response for all open ports of containers
+    ports: array of port numbers
+    """
+    ports: dict[int, list[int]]

src/pwncore/models/responseModels/leaderboard_response.py

@@ -0,0 +1,11 @@
+from pydantic import BaseModel
+
+# defining Pydantic response model
+class LeaderboardEntry(BaseModel):
+    """
+    Returns the leaderboard entry for a team.
+    name: team name
+    tpoints: total points
+    """
+    name: str
+    tpoints: int

src/pwncore/models/responseModels/preEventCTF_response.py

@@ -0,0 +1,33 @@
+from pydantic import BaseModel
+
+# pydantic response models 
+class PreEventFlag(BaseModel):
+    """
+    Response for pre-event flag submission
+    """
+    tag: str
+    flag: str
+    email: str
+
+
+class CoinsQuery(BaseModel):
+    """
+    Response for pre-event coins query
+    """
+    tag: str
+
+class CoinsResponse(BaseModel):
+    """
+    Response for pre-event coins query
+    """
+    coins: int
+
+class FlagSubmissionResponse(BaseModel):
+    """
+    Response for pre-event flag submission
+    """
+    status: bool
+    coins: int
+
+class preEventCTF_ErrorResponse(BaseModel):
+    msg_code: int

src/pwncore/models/responseModels/teamAuthResponse.py

@@ -0,0 +1,62 @@
+from pydantic import BaseModel
+import typing as t
+
+# defining Pydantic response models
+class AuthBody(BaseModel):
+    """
+    Request body for login
+    name: name of the user
+    password: password of the user
+    """
+    name: str
+    password: str
+
+
+class SignupBody(BaseModel):
+    name: str
+    password: str
+    tags: set[str]
+
+
+# Response Models
+class SignupResponse(BaseModel):
+    """
+    msg_code: 13 (signup_success)
+    """
+    msg_code: t.Literal[13]
+
+class SignupErrorUsersNotFound(BaseModel):
+    """
+    msg_code: 24 (users_not_found)
+    tags: list[str]
+    """
+    msg_code: t.Literal[24]
+    tags: list[str]
+
+class SignupErrorUsersInTeam(BaseModel):
+    """
+    msg_code: 20 (user_already_in_team)
+    tags: list[str]
+    """
+    msg_code: t.Literal[20]
+    tags: list[str]
+
+class LoginResponse(BaseModel):
+    """
+    msg_code: 15 (login_success)
+    access_token: JWT access token
+    token_type: "bearer"
+    """
+    msg_code: t.Literal[15]
+    access_token: str
+    token_type: str
+
+class Auth_ErrorResponse(BaseModel):
+    """
+    msg_code can be:
+    0 (db_error)
+    17 (team_exists)
+    10 (team_not_found)
+    14 (wrong_password)
+    """
+    msg_code: t.Literal[0, 17, 10, 14]

src/pwncore/models/responseModels/teamManagementResponse.py

@@ -0,0 +1,34 @@
+from pydantic import BaseModel
+import typing as t
+
+
+class UserAddBody(BaseModel):
+    """
+    Request body for adding a user
+    """
+    tag: str
+    name: str
+    email: str
+    phone_num: str
+
+
+class UserRemoveBody(BaseModel):
+    """
+    Request body for removing a user
+    """
+    tag: str
+
+class MemberStatusResponse(BaseModel):
+    """
+    Response for user management operations in teams
+    msg_code for response:
+    - (success) 
+        - user_added: 18
+        - user_removed: 19
+
+    - (fail) 
+        - user_already_in_team: 20
+        - user_not_in_team : 21
+        - db_error: 0
+    """
+    msg_code: int

src/pwncore/models/responseModels/userManagementResponse.py

@@ -0,0 +1,31 @@
+from pydantic import BaseModel
+import typing as t
+
+class UserAddBody(BaseModel):
+    """
+    Request body for adding a user
+    tag: team tag
+    name: name of the user
+    email: email of the user
+    phone_num: phone number of the user
+    """
+    tag: str
+    name: str
+    email: str
+    phone_num: str
+
+
+class UserRemoveBody(BaseModel):
+    """
+    Request body for removing a user
+    tag: team tag
+    """
+    tag: str
+
+
+class MessageResponse(BaseModel):
+    """
+    Response for user management operations
+    msg_code: message code
+    """
+    msg_code: int

src/pwncore/routes/admin.py

@@ -4,6 +4,8 @@
 from fastapi import APIRouter, Request, Response
 from passlib.hash import bcrypt, bcrypt_sha256
 from tortoise.transactions import atomic, in_transaction
+from pydantic import BaseModel
+from typing import Optional
 
 import pwncore.containerASD as containerASD
 from pwncore.config import config
@@ -51,14 +53,21 @@ async def _del_cont(id: str):
     await container.delete()
 
 
+class AdminResponse(BaseModel):
+    success: bool
+    message: Optional[str] = None
+
+     
 @atomic()
-@router.get("/union")
+@router.get("/union",
+    response_model=AdminResponse,
+    )
 async def calculate_team_coins(
     response: Response, req: Request
 ):  # Inefficient, anyways will be used only once
     if not bcrypt_sha256.verify((await req.body()).strip(), config.admin_hash):  # Use config.admin_hash
         response.status_code = 401
-        return
+        return AdminResponse(success=False, message="Authentication failed")
     async with in_transaction():
         logging.info("Calculating team points form pre-event CTFs:")
         team_ids = await Team.filter().values_list("id", flat=True)
@@ -82,14 +91,18 @@ async def calculate_team_coins(
             logging.info(f"{team.id}) {team.name}: {team.coins}")
             await team.save()
 
+    return AdminResponse(success=True, message="Team coins updated successfully")
 
-@router.get("/create")
+     
+@router.get("/create",
+    response_model=AdminResponse
+    )
 async def init_db(
     response: Response, req: Request
 ):  # Inefficient, anyways will be used only once
     if not bcrypt_sha256.verify((await req.body()).strip(), config.admin_hash):  
         response.status_code = 401
-        return
+        return AdminResponse(success=False, message="Authentication failed")
     await Problem.create(
         name="Invisible-Incursion",
         description="Chod de tujhe se na ho paye",
@@ -207,3 +220,5 @@ async def init_db(
     await SolvedProblem.create(team_id=2, problem_id=1)
     await SolvedProblem.create(team_id=2, problem_id=2)
     await SolvedProblem.create(team_id=1, problem_id=2)
+
+    return AdminResponse(success=True, message="Database initialized with sample data")