Chapter 3.5: Automatic Swagger Documentation
Time to learn: 30 minutes
1. API Documentation: The Space Station's Operating Manual
Imagine you are a new astronaut arriving at the ISS. How do you know which switch does what and how to operate the robotic arm? You need a detailed and up-to-date manual.
API documentation is the same kind of manual for developers. It explains:
- Which "docking ports" (endpoints) are available.
- Which "commands" (HTTP methods) can be sent.
- What "cargo" (data) needs to be transmitted.
- What "telemetry" (responses) to expect.
The problem is that writing documentation manually is long, boring, and it almost always becomes outdated.
💡 Space Analogy:
Manual documentation is like paper blueprints that sit in an archive and are not updated after the station is upgraded. FastAPI's automatic documentation is an interactive display in Mission Control that updates in real-time after every change on the station.
2. The Magic of FastAPI: How Does It Work?
FastAPI does all the "dirty work" for you, based on your own code. It scans:
- Routes: All decorators like
@app.get
,@app.post
, etc. - Parameters: Path parameters (
ship_id: int
) and query parameters. - Pydantic Models: Your "blueprints" (
Spaceship
,SpaceshipCreate
). - Docstrings: The descriptions you write in triple quotes.
Based on this data, FastAPI generates a schema according to the OpenAPI standard (formerly known as Swagger) and then displays it through two beautiful interfaces.
3. Exploring the "Mission Control Display": Swagger UI
Swagger UI is an interactive interface that allows you not only to read the documentation but also to test the API directly from the browser.
Open http://127.0.0.1:8000/docs
You will see:
- List of Endpoints: Grouped by tags (by default, by the resource name) and colored according to the HTTP methods.
- Descriptions: The text from your docstrings (
"""..."""
) is displayed as endpoint descriptions. - Parameters: Shows which parameters (like
ship_id
) the endpoint expects, their type, and whether they are required. - Request Body: For
POST
andPUT
, it shows a JSON schema generated from your Pydantic model (SpaceshipCreate
). - Responses: Shows possible status codes and response schemas based on the
response_model
. - "Try it out" Button: Allows you to fill in the parameters and send a real request to your server.
4. Improving the Documentation: Tags and Descriptions
Let's make our documentation even more professional.
Step 1: Add metadata to the FastAPI
instance
You can pass general information about your API when creating the app
.
Modify the app = FastAPI()
line in main.py
:
# main.py
app = FastAPI(
title="Fleet Management API",
description="API for managing a fleet of spacecraft.",
version="1.0.0",
)
Step 2: Group endpoints using tags You can add tags to each endpoint to group them logically.
Add the tags
parameter to the decorators:
# GET /spaceships
@app.get("/spaceships", response_model=List[Spaceship], tags=["Spacecraft"])
# ...
# GET /spaceships/{ship_id}
@app.get("/spaceships/{ship_id}", response_model=Spaceship, tags=["Spacecraft"])
# ...
# POST /spaceships
@app.post("/spaceships", response_model=Spaceship, status_code=201, tags=["Spacecraft"])
# ...
# and so on for PUT and DELETE
5. The Alternative View: ReDoc
FastAPI provides another documentation interface out of the box — ReDoc. It is less interactive, but often considered more readable and is excellent for static documentation.
Open http://127.0.0.1:8000/redoc
You will see a three-column layout with navigation, endpoint descriptions, and data schemas. This is a great way to provide documentation to your "clients" (for example, the frontend team).
Review Quiz
🚀 Chapter Summary:
You have seen one of FastAPI's most powerful "superpowers"—creating documentation without any effort.
- 📖 Your API now has two types of up-to-date documentation: Swagger UI and ReDoc.
- 🔬 The documentation is interactive and allows you to test the API on the fly.
- 🏷️ You have learned to improve it with metadata and tags.
The operating manual is ready and always up-to-date! In the final chapter of this section, we will learn how to handle "cosmic anomalies"—errors and invalid data.
📌 Checkpoint:
- Make sure that the title, description, and tagged endpoints are displayed at
http://127.0.0.1:8000/docs
.- Check that your
Spaceship
model is visible in the "Schemas" section.- Open
http://127.0.0.1:8000/redoc
and appreciate the alternative view.⚠️ If changes are not displayed:
- Make sure you have saved the
main.py
file.- Check that the
uvicorn
server is running with the--reload
flag and has restarted successfully.