Module 13 Exercises: Crafting the Perfect Docs

A well-documented API is a usable API. These exercises will help you think from the perspective of the developer who will eventually use your code.

---

Exercise 1: The Tag Strategist

You have an API with the following endpoints:

• POST /login
• GET /profile
• POST /admin/ban-user
• GET /admin/server-stats
• GET /orders

Suggest a logical way to group these into Three Tags to make the Swagger UI cleaner.

---

Exercise 2: Implementing a Sample Payload

Write a Pydantic model called SupportTicket.

• Include an id, subject, and priority.
• Use Field(..., examples=[...]) to provide a realistic sample for a high-priority ticket about a login failure.

---

Exercise 3: Documenting Failure

Take a standard endpoint @app.get("/items/{id}"). Use the responses parameter in the decorator to document that if the id is invalid, the API returns a 400 Bad Request with the detail "Invalid ID format".

---

Self-Correction / Discussion

Exercise 1 Answer:

1. Auth: /login
2. User Operations: /profile, /orders
3. Admin Control: /admin/ban-user, /admin/server-stats

Exercise 2 Answer:

class SupportTicket(BaseModel):
    id: str = Field(..., examples=["TKT-12345"])
    subject: str = Field(..., examples=["Unable to log in via Google"])
    priority: int = Field(..., examples=[1])

Exercise 3 Answer:

@app.get(
    "/items/{id}", 
    responses={400: {"description": "Invalid ID format"}}
)
async def get_item(id: str):
    ...

---

Summary of Module 13

You have moved from "Building" to "Publishing."

• Metadata: Your API now has a name, a version, and a brand.
• Context: You are providing examples and descriptions that make integration easy.
• Standardization: You are speaking the universal language of OpenAPI.

In Module 14: Testing FastAPI Applications, we will learn how to verify that our code actually does what the documentation says it does.