Add comments at the top of the file to document routes

src/routes/blog.py

@@ -1,12 +1,13 @@
 """
-This module defines API routes for managing blogs
-
 Routes:
-1. GET all blogs
-2. GET blog by ID
-3. ADD a new blog
-4. Edit (PUT) and existing blog by ID
-5. DELETE a blog by ID
+1. GET all blogs - Retrieve all blogs from the database.
+2. GET blog by ID - Retrieve a specific blog by its ID.
+3. GET limited blogs - Retrieve a limited number of blogs.
+4. GET all blogs (private) - Retrieve all blogs for authenticated users.
+5. GET blog by ID (private) - Retrieve a specific blog by its ID for authenticated users.
+6. ADD a new blog - Add a new blog to the database.
+7. EDIT a blog by ID - Edit an existing blog by its ID.
+8. DELETE a blog by ID - Delete a blog by its ID.
 """
 
 from fastapi import APIRouter, Depends, HTTPException

src/routes/book.py

@@ -1,12 +1,10 @@
 """
-This module defines API routes for managing book
-
-Routes:
-1. GET all book
-2. GET book by ID
-3. ADD a new book
-4. Edit (PUT) and existing book by ID
-5. DELETE an experience by ID
+Routes Overview:
+1. GET / - Retrieve all books from the database.
+2. GET /{_id} - Retrieve a book by its ID.
+3. POST / - Add a new book to the database.
+4. PUT /{_id} - Edit an existing book by its ID.
+5. DELETE /{_id} - Delete a book by its ID.
 """
 
 from fastapi import APIRouter, Depends, HTTPException

src/routes/comments.py

@@ -1,3 +1,12 @@
+"""
+Routes Overview:
+1. GET / - Retrieve all comments from the database.
+2. GET /{blog_id} - Retrieve all comments for a specific blog post from the database.
+3. POST /{blog_id} - Add a new comment to a specific blog post in the database.
+4. PUT /{blog_id}/{comment_id} - Edit an existing comment by its ID for a specific blog post.
+5. DELETE /{blog_id}/{comment_id} - Delete a comment by its ID for a specific blog post.
+"""
+
 from fastapi import APIRouter
 
 from src.domain.comments import Comment

src/routes/contact.py

@@ -1,3 +1,11 @@
+"""
+Routes Overview:
+1. POST / - Endpoint for clients to send an email and store it in the database.
+2. GET / - Retrieve all emails from the database (private route, requires authentication).
+3. GET /{_id} - Retrieve an email by its ID (private route, requires authentication).
+4. DELETE /{_id} - Delete an email by its ID (private route, requires authentication).
+"""
+
 from fastapi import APIRouter, Depends, HTTPException
 
 from src.domain.contact import Contact

src/routes/experiences.py

@@ -1,12 +1,12 @@
 """
-This module defines API routes for managing experiences
-
-Routes:
-1. GET all experiences
-2. GET experiences by ID
-3. ADD a new experiences
-4. Edit (PUT) and existing experiences by ID
-5. DELETE an experience by ID
+Routes Overview:
+1. GET / - Retrieves all experiences from the database (public).
+2. GET /{_id} - Retrieves a specific experience by its ID (public).
+3. GET /admin/ - Retrieves all experiences from the database (private).
+4. POST / - Adds a new experience to the database (private).
+5. GET /admin/{_id} - Retrieves a specific experience by its ID (private).
+6. PUT /{_id} - Updates an existing experience by its ID (private).
+7. DELETE /{_id} - Deletes an experience from the database by its ID (private).
 """
 
 from fastapi import APIRouter, Depends, HTTPException

src/routes/github.py

@@ -12,6 +12,12 @@
 # Route handler to fetch GitHub repositories
 @router.get('/')
 async def get_repo():
+    """
+    Route handler to fetch GitHub repositories of a specific user.
+
+    Returns:
+        dict: A dictionary containing the fetched repositories.
+    """
     # Constructing the URL to fetch user repositories from GitHub API
     url = f"https://api.github.com/users/{env.GITHUB}/repos"
 

src/routes/links.py

@@ -1,12 +1,11 @@
 """
-This module defines API routes for managing links
-
-Routes:
-1. GET all links
-2. GET links by ID
-3. ADD a new links
-4. Edit (PUT) and existing links by ID
-5. DELETE a links by ID
+Routes Overview:
+1. GET / - Retrieve all links from the database.
+2. GET /admin/ - Retrieve all links from the database (private).
+3. POST / - Add a new link to the database (private).
+4. GET /{_id} - Retrieve a link by its ID (private).
+5. PUT /{_id} - Edit a link by its ID (private).
+6. DELETE /{_id} - Delete a link by its ID (private).
 """
 
 from fastapi import APIRouter, Depends, HTTPException

src/routes/login.py

@@ -1,3 +1,8 @@
+"""
+Routes Overview:
+1. POST / - User authentication route to obtain an access token.
+"""
+
 from datetime import timedelta
 from typing import Annotated
 

src/routes/newsletter.py

@@ -1,9 +1,17 @@
+"""
+Routes Overview:
+1. GET / - Retrieve all newsletters from the database.
+2. GET /{_id} - Retrieve a specific newsletter by its ID from the database.
+3. DELETE /{_id} - Delete a specific newsletter by its ID from the database.
+4. POST / - Add and send a new newsletter to all recipients.
+"""
+
 from fastapi import APIRouter, HTTPException, Depends
 
 from src.domain.newsletter import Newsletter
 from src.services import newsletters, db
-from src.template import newsletter_body
 from src.services.security import get_current_user
+from src.template import newsletter_body
 
 router = APIRouter()
 
@@ -109,5 +117,3 @@ async def send_newsletter_to_all(newsletter: Newsletter, current_user: str = Dep
     else:
         # If the insertion was not acknowledged, return None
         return None
-
-

src/routes/projects.py

@@ -1,3 +1,12 @@
+"""
+Routes Overview:
+1. GET / - Retrieve all projects from the database.
+2. GET /{_id} - Retrieve a specific project by its ID from the database.
+3. DELETE /{_id} - Delete a specific project by its ID from the database.
+4. POST / - Add a new project to the database.
+5. PUT /{_id} - Edit an existing project by its ID in the database.
+"""
+
 from fastapi import APIRouter, Depends, HTTPException
 
 from src.domain.projects import Projects

src/routes/register.py

@@ -1,3 +1,9 @@
+"""
+Routes:
+1. Register new user - Register a new user and store their data in the database.
+2. Confirm registration - Confirm a user's registration via a confirmation link.
+"""
+
 from datetime import timedelta
 
 from fastapi import APIRouter, HTTPException

src/routes/subscriber.py

@@ -1,3 +1,14 @@
+"""
+Routes Overview:
+1. GET / - Retrieve all subscribers from the database.
+2. GET /{_id} - Retrieve a subscriber by their ID.
+3. POST / - Add a new subscriber to the database.
+4. PUT /{_id} - Edit an existing subscriber by their ID.
+5. DELETE /{_id} - Delete a subscriber by their ID.
+6. POST /subscribe - Subscribe a client to the newsletter and send a confirmation email.
+7. GET /confirm/{token} - Confirm a client's email for the newsletter subscription.
+"""
+
 from datetime import timedelta
 
 from fastapi import APIRouter, HTTPException, Depends, status
@@ -164,7 +175,7 @@ async def subscribe(subscriber: Subscriber):
 
     # Generate the confirmation email's HTML content
     body = confirmation_newsletter_email.html(link=f'{env.DOMAIN}/subscribers/confirm/{token}', name=subscriber.name,
-                                   surname=subscriber.surname)
+                                              surname=subscriber.surname)
 
     # Send the confirmation email to the subscriber
     if not emails.send_confirm(email_to=subscriber.email,

src/routes/user.py

@@ -1,3 +1,14 @@
+"""
+Routes Overview:
+1. GET / - Retrieves all users from the database (public).
+2. GET /{_id} - Retrieves a user by their ID (public).
+3. GET /admin/ - Retrieves all users from the database (private).
+4. POST / - Adds a new user to the database (private).
+5. GET /admin/{_id} - Retrieves a user by their ID (private).
+6. PUT /{_id} - Edits a user by their ID (private).
+7. DELETE /{_id} - Deletes a user by their ID (private).
+"""
+
 from fastapi import APIRouter, Depends, HTTPException
 
 from src.domain.user import User