Unit 03.04: Reading the automatic documentation critically

The automatic documentation is generated from your types, so it cannot drift - and it cannot show everything.

What it captures and what it cannot

An endpoint with a described field, a summary and a docstring, and the resulting schema.

The code prints what was generated.

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI(title="Classifier", version="1.0.0")


class Request(BaseModel):
    text: str = Field(min_length=1, max_length=4000,
                      description="the ticket text to classify")


@app.post("/classify", summary="Classify a support ticket")
def classify(body: Request) -> dict:
    """Returns one of four categories. Never logs the request body."""
    return {"category": "billing"}


schema = app.openapi()
path = schema["paths"]["/classify"]["post"]
print(f"summary     : {path['summary']}")
print(f"description : {path['description'].strip()}")
props = schema["components"]["schemas"]["Request"]["properties"]["text"]
print(f"text field  : {props}")

print("\nThe docs came from the types and the docstring, so they cannot drift.")
print("What they cannot show: the guarantee about not logging. Write that down.")

The field description, the summary and the docstring all reached the schema without being written twice. That is the main benefit: documentation that is a projection of the code rather than a parallel artefact that goes stale.

What it cannot show is the guarantee - "never logs the request body" is in the docstring here, and it is prose. Behavioural promises have to be written down and tested separately.

The mistake this prevents

The mistake is treating the generated page as the whole contract. It documents shapes and status codes and says nothing about rate limits, retention, idempotency or what you do with the data.

Takeaway

Generated docs cover shapes and codes and cannot express guarantees. Write the behavioural promises down separately and test them.

Mark complete