Merge pull request #162 from nanotaboada/feature/docstrings

chore: add API docs section

Author: nanotaboada

.vscode/launch.json

@@ -1,13 +1,13 @@
 {
-    "version": "0.2.0",
-    "configurations": [
-        {
-            "name": "Python Debugger: FastAPI",
-            "type": "debugpy",
-            "request": "launch",
-            "module": "uvicorn",
-            "args": ["main:app", "--reload", "--port", "9000"],
-            "jinja": true
-        }
-    ]
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Python: Launch FastAPI (Debug)",
+      "type": "debugpy",
+      "request": "launch",
+      "module": "uvicorn",
+      "args": ["main:app", "--reload", "--port", "9000"],
+      "jinja": true
+    }
+  ]
 }

README.md

@@ -35,6 +35,14 @@ pip install --requirement requirements.txt
 uvicorn main:app --reload --port 9000
 ```
 
+## Documentation
+
+```console
+http://localhost:9000/docs
+```
+
+![API Documentation](python-samples-fastapi-restful-docs.png)
+
 ## Credits
 
 The solution has been coded using [Visual Studio Code](https://code.visualstudio.com/) with the official [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) extension.

main.py

@@ -14,5 +14,9 @@ async def lifespan(app: FastAPI):
     FastAPICache.init(InMemoryBackend())
     yield
 
-app = FastAPI(lifespan=lifespan)
+app = FastAPI(lifespan=lifespan,
+              title="python-samples-fastapi-restful",
+              description="🧪 Proof of Concept for a RESTful API made with Python 3 and FastAPI",
+              version="1.0.0",)
+
 app.include_router(player_route.api_router)

models/player_model.py

@@ -28,17 +28,17 @@ class PlayerModel(MainModel):
     Pydantic model representing a football Player.
 
     Attributes:
-        id (int): The unique identifier for the player.
-        first_name (str): The first name of the player.
-        middle_name (Optional[str]): The middle name of the player, if any.
-        last_name (str): The last name of the player.
-        date_of_birth (Optional[str]): The date of birth of the player, if provided.
-        squad_number (int): The unique squad number assigned to the player.
-        position (str): The playing position of the player.
-        abbr_position (Optional[str]): The abbreviated form of the player's position, if any.
-        team (Optional[str]): The team to which the player belongs, if any.
+        id (int): The unique identifier for the Player.
+        first_name (str): The first name of the Player.
+        middle_name (Optional[str]): The middle name of the Player, if any.
+        last_name (str): The last name of the Player.
+        date_of_birth (Optional[str]): The date of birth of the Player, if provided.
+        squad_number (int): The unique squad number assigned to the Player.
+        position (str): The playing position of the Player.
+        abbr_position (Optional[str]): The abbreviated form of the Player's position, if any.
+        team (Optional[str]): The team to which the Player belongs, if any.
         league (Optional[str]): The league where the team plays, if any.
-        starting11 (Optional[bool]): Indicates if the player is in the starting 11, if provided.
+        starting11 (Optional[bool]): Indicates if the Player is in the starting 11, if provided.
     """
     id: int
     first_name: str

python-samples-fastapi-restful-docs.png

@@ -37,7 +37,8 @@ def get_orm_session():
 @api_router.post(
     "/players/",
     status_code=status.HTTP_201_CREATED,
-    summary="Creates a new Player"
+    summary="Creates a new Player",
+    tags=["Players"]
 )
 def post(
     player_model: PlayerModel = Body(...),
@@ -69,7 +70,8 @@ def post(
     "/players/",
     response_model=List[PlayerModel],
     status_code=status.HTTP_200_OK,
-    summary="Retrieves a collection of Players"
+    summary="Retrieves a collection of Players",
+    tags=["Players"]
 )
 @cache(expire=CACHING_TIME_IN_SECONDS)
 def get_all(
@@ -93,7 +95,8 @@ def get_all(
     "/players/{player_id}",
     response_model=PlayerModel,
     status_code=status.HTTP_200_OK,
-    summary="Retrieves a Player by its Id"
+    summary="Retrieves a Player by its Id",
+    tags=["Players"]
 )
 @cache(expire=CACHING_TIME_IN_SECONDS)
 def get_by_id(
@@ -125,7 +128,8 @@ def get_by_id(
     "/players/squadnumber/{squad_number}",
     response_model=PlayerModel,
     status_code=status.HTTP_200_OK,
-    summary="Retrieves a Player by its Squad Number"
+    summary="Retrieves a Player by its Squad Number",
+    tags=["Players"]
 )
 @cache(expire=CACHING_TIME_IN_SECONDS)
 def get_by_squad_number(
@@ -158,7 +162,8 @@ def get_by_squad_number(
 @api_router.put(
     "/players/{player_id}",
     status_code=status.HTTP_204_NO_CONTENT,
-    summary="Updates an existing Player"
+    summary="Updates an existing Player",
+    tags=["Players"]
 )
 def put(
     player_id: int = Path(..., title="The ID of the Player"),
@@ -174,7 +179,7 @@ def put(
         orm_session (Session): The SQLAlchemy ORM session.
 
     Raises:
-        HTTPException: HTTP 404 Not Found error if the player with the specified ID does not exist.
+        HTTPException: HTTP 404 Not Found error if the Player with the specified ID does not exist.
     """
     player = player_service.retrieve_by_id(orm_session, player_id)
 
@@ -191,7 +196,8 @@ def put(
 @api_router.delete(
     "/players/{player_id}",
     status_code=status.HTTP_204_NO_CONTENT,
-    summary="Deletes an existing Player"
+    summary="Deletes an existing Player",
+    tags=["Players"]
 )
 def delete(
     player_id: int = Path(..., title="The ID of the Player"),

routes/player_route.py

@@ -12,7 +12,8 @@
 
 
 def create(orm_session: Session, player_model: PlayerModel):
-    """Creates a new Player in the database.
+    """
+    Creates a new Player in the database.
 
     Args:
         orm_session: The SQLAlchemy ORM session instance.
@@ -36,7 +37,8 @@ def create(orm_session: Session, player_model: PlayerModel):
 
 
 def retrieve_all(orm_session: Session):
-    """Retrieves all the players from the database.
+    """
+    Retrieves all the players from the database.
 
     Args:
         orm_session: The SQLAlchemy ORM session instance.
@@ -51,7 +53,8 @@ def retrieve_all(orm_session: Session):
 
 
 def retrieve_by_id(orm_session: Session, player_id: int):
-    """Retrieves a Player by its ID from the database.
+    """
+    Retrieves a Player by its ID from the database.
 
     Args:
         orm_session: The SQLAlchemy ORM session instance.
@@ -65,7 +68,8 @@ def retrieve_by_id(orm_session: Session, player_id: int):
 
 
 def retrieve_by_squad_number(orm_session: Session, squad_number: int):
-    """Retrieves a Player by its Squad Number from the database.
+    """
+    Retrieves a Player by its Squad Number from the database.
 
     Args:
         orm_session: The SQLAlchemy ORM session instance.
@@ -82,7 +86,8 @@ def retrieve_by_squad_number(orm_session: Session, squad_number: int):
 
 
 def update(orm_session: Session, player_model: PlayerModel):
-    """Updates (entirely) an existing Player in the database.
+    """
+    Updates (entirely) an existing Player in the database.
 
     Args:
         orm_session: The SQLAlchemy ORM session instance.
@@ -115,7 +120,8 @@ def update(orm_session: Session, player_model: PlayerModel):
 
 
 def delete(orm_session: Session, player_id: int):
-    """Deletes an existing Player from the database.
+    """
+    Deletes an existing Player from the database.
 
     Args:
         orm_session: The SQLAlchemy ORM session instance.

services/player_service.py

@@ -1,4 +1,8 @@
 class Player:
+    """
+    Test stub representing a Player.
+    """
+
     def __init__(
         self,
         id=None,