docs: API routes documentation

README.md

@@ -15,3 +15,38 @@ This repo uses [pre-commit](https://pre-commit.com/) to enforce code styling, et
 ```console
 pre-commit run
 ```
+
+### Get started
+1. Clone this repository :
+```console
+git clone https://github.com/openfoodfacts/nutripatrol.git
+```
+
+2. Open it
+```console
+cd nutripatrol
+```
+
+3. Make docker containers
+```console
+docker-compose up -d
+```
+
+4. Install virtual environment python
+```console
+python3 -m venv venv
+```
+
+5. Activate it 
+```console
+# MacOS or Linux
+source venv/bin/activate
+
+# Windows
+venv/Scripts/activate
+```
+
+6. Install requirement.txt dependencies
+```console
+pip3 install -r requirements.txt
+```

app/api.py

@@ -211,9 +211,15 @@ class Flag(FlagCreate):
     device_id: str = Field(..., description="Device ID of the flagger")
 
 
-# Create a flag (one to one relationship)
 @api_v1_router.post("/flags")
 def create_flag(flag: FlagCreate, request: Request):
+    """Create a flag for a product.
+
+    This function is used to create a flag for a product or an image.
+    At th same time, it creates a ticket if it does not exist for this product or image.
+
+    :return: the created flag with the assigned ticket
+    """
     with db:
         # Check if the flag already exists
         if (
@@ -261,16 +267,27 @@ def create_flag(flag: FlagCreate, request: Request):
         )
 
 
-# Get all flags (one to many relationship)
 @api_v1_router.get("/flags")
 def get_flags():
+    """Get all flags.
+
+    This function is used to get all flags.
+
+    :return: a list of flags
+    """
     with db:
         return {"flags": list(FlagModel.select().dicts().iterator())}
 
 
-# Get flag by ID (one to one relationship)
 @api_v1_router.get("/flags/{flag_id}")
 def get_flag(flag_id: int):
+    """Get a flag by ID.
+
+    This function is used to get a flag by its ID.
+
+    :param flag_id: the ID of the flag
+    :return: the flag
+    """
     with db:
         try:
             return FlagModel.get_by_id(flag_id)
@@ -282,33 +299,55 @@ def _create_ticket(ticket: TicketCreate):
     return TicketModel.create(**ticket.model_dump())
 
 
-# Create a ticket (one to one relationship)
 @api_v1_router.post("/tickets")
 def create_ticket(ticket: TicketCreate) -> Ticket:
+    """Create a ticket.
+
+    This function is used to create a ticket for a product or an image.
+
+    :return: the created ticket
+    """
     with db:
         return _create_ticket(ticket)
 
 
-# Get all tickets (one to many relationship)
 @api_v1_router.get("/tickets")
 def get_tickets():
+    """Get all tickets.
+
+    This function is used to get all tickets.
+
+    :return: a list of tickets
+    """
     with db:
         return {"tickets": list(TicketModel.select().dicts().iterator())}
 
 
-# Get ticket by id (one to one relationship)
 @api_v1_router.get("/tickets/{ticket_id}")
 def get_ticket(ticket_id: int):
+    """Get a ticket by ID.
+
+    This function is used to get a ticket by its ID.
+
+    :param ticket_id: the ID of the ticket
+    :return: the ticket
+    """
     with db:
         try:
             return model_to_dict(TicketModel.get_by_id(ticket_id))
         except DoesNotExist:
             raise HTTPException(status_code=404, detail="Not found")
 
 
-# Get all flags for a ticket by id (one to many relationship)
 @api_v1_router.get("/tickets/{ticket_id}/flags")
 def get_flags_by_ticket(ticket_id: int):
+    """Get all flags for a ticket by ID.
+
+    This function is used to get all flags for a ticket by its ID.
+
+    :param ticket_id: the ID of the ticket
+    :return: a list of flags
+    """
     with db:
         return {
             "flags": list(
@@ -320,9 +359,16 @@ def get_flags_by_ticket(ticket_id: int):
         }
 
 
-# Update ticket status by id with enum : open, closed (soft delete)
 @api_v1_router.put("/tickets/{ticket_id}/status")
 def update_ticket_status(ticket_id: int, status: TicketStatus):
+    """Update the status of a ticket by ID.
+
+    This function is used to update the status of a ticket by its ID.
+
+    :param ticket_id: the ID of the ticket
+    :param status: the new status of the ticket
+    :return: the updated ticket
+    """
     with db:
         try:
             ticket = TicketModel.get_by_id(ticket_id)