Improved FastAPI docs

README.md

@@ -29,7 +29,7 @@ EchoPages is a service designed to provide users with scheduled digests of their
 - Git
 - A [Postmark](https://postmarkapp.com/) account, and a Postmark API token
 
-### Installation
+### Installation and Usage
 
 1. **Clone the Repository:**
 
@@ -55,13 +55,11 @@ EchoPages is a service designed to provide users with scheduled digests of their
   docker-compose --env-file /path/to/your/file.env up -d
   ```
 
-4. **Access the Application:**
+4. **Explore the API docs:**
 
-  The application will be available at `http://localhost:8000`.
+  The application will be available at `http://localhost:8000`. You can access the API documentation in `http://localhost:8000/docs`.
 
-### Usage
-
-1. **Add Content:**
+5. **Add Content:**
 
   Use the `/add_content` endpoint to add new content. You can do this via an HTTP client like curl or Postman:
 
@@ -86,7 +84,6 @@ EchoPages is a service designed to provide users with scheduled digests of their
 
   You'll have to convert the image to embed it (you can find an utility function to do this in [this file](utils/markdown_processing.py)):
   ```
-  
     # Some Nice Book Chapter Summary
     
     # Topic 1
@@ -99,9 +96,9 @@ EchoPages is a service designed to provide users with scheduled digests of their
     * Key point 2: Yet another thing
   ```
   
-2. **Receive Digest:**
+6. **Receive Digest:**
 
-  The application will automatically send out digests based on your configured schedule.
+  That's it! The application will automatically send you digests based on your content and your configured schedule.
 
 ## Contributing 🤝
 

echopages/api/endpoints.py

@@ -1,22 +1,40 @@
 from datetime import datetime
 
 from fastapi import Depends, FastAPI, HTTPException, status
-from pydantic import BaseModel, field_validator
+from pydantic import BaseModel, Field, field_validator
 
 import echopages.config
 from echopages import bootstrap
 from echopages.application import services
 from echopages.domain import model, repositories
 from echopages.infrastructure.delivery import schedulers
 
-app = FastAPI()
+app = FastAPI(
+    title="EchoPages API",
+    description="Read, Repeat, Retain.",
+    version="0.1.0",
+)
 
 
 class AddContentRequest(BaseModel):
-    source: str = ""
-    author: str = ""
-    location: str = ""
-    text: str = ""
+    source: str = Field(
+        "",
+        description="The source of the content.",
+        examples=["Book Name", "Article Title"],
+    )
+    author: str = Field(
+        "", description="The author of the content.", examples=["Sample Author"]
+    )
+    location: str = Field(
+        "",
+        description="The location of the content.",
+        examples=["Chapter 1", "Section 1.1", "Page 75"],
+    )
+    text: str = Field(
+        "",
+        description="The text of the content.",
+        examples=["Some long *markdown* summary."],
+    )
 
 
 class AddContentResponse(BaseModel):
@@ -34,6 +52,7 @@ class GetContentResponse(BaseModel):
     "/add_content",
     status_code=status.HTTP_201_CREATED,
     response_model=AddContentResponse,
+    summary="Add new content",
 )
 async def add_content(
     content: AddContentRequest,
@@ -46,7 +65,11 @@ async def add_content(
     return AddContentResponse(content_id=content_id)
 
 
-@app.get("/contents/{content_id}", response_model=GetContentResponse)
+@app.get(
+    "/contents/{content_id}",
+    response_model=GetContentResponse,
+    summary="Get content by ID",
+)
 async def get_content(
     content_id: int,
     uow: repositories.UnitOfWork = Depends(bootstrap.get_unit_of_work),
@@ -60,15 +83,19 @@ async def get_content(
 
 
 class TriggerDigest(BaseModel):
-    n_units: int = 1
+    n_units: int = Field(1, description="The number of units to include in the digest.")
 
 
 class TriggerDigestResponse(BaseModel):
     digest_title: str
     digest_content_str: str
 
 
-@app.post("/trigger_digest")
+@app.post(
+    "/trigger_digest",
+    response_model=TriggerDigestResponse,
+    summary="Trigger a digest generation and delivery",
+)
 async def trigger_digest(
     trigger_digest_request: TriggerDigest,
     uow: repositories.UnitOfWork = Depends(bootstrap.get_unit_of_work),
@@ -93,7 +120,11 @@ async def trigger_digest(
 
 
 class Schedule(BaseModel):
-    time_of_day: str
+    time_of_day: str = Field(
+        ...,
+        description="The time of day at which the digest should be generated, in format HH:MM.",
+        examples=["07:00", "15:30"],
+    )
 
     @field_validator("time_of_day")
     def check_time_format(cls, v: str) -> str:
@@ -105,7 +136,11 @@ class ConfigureScheduleResponse(BaseModel):
     message: str = "Schedule updated"
 
 
-@app.post("/configure_schedule")
+@app.post(
+    "/configure_schedule",
+    response_model=ConfigureScheduleResponse,
+    summary="Configure schedule parameters",
+)
 async def configure_schedule(
     schedule: Schedule,
     uow: repositories.UnitOfWork = Depends(bootstrap.get_unit_of_work),