Skip to content

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:

  1. Routes: All decorators like @app.get, @app.post, etc.
  2. Parameters: Path parameters (ship_id: int) and query parameters.
  3. Pydantic Models: Your "blueprints" (Spaceship, SpaceshipCreate).
  4. 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 and PUT, 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",
)
Now, a title and description will appear at the top of your documentation.

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
Now all your CRUD operations will be neatly grouped under the "Spacecraft" heading.


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

1. FastAPI generates documentation based on...

2. What standard is the basis for FastAPI's auto-documentation?

3. At what URL is the interactive Swagger UI documentation available by default?

4. The `tags` parameter in the `@app.get` decorator is used for:

5. ReDoc is...


🚀 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.