Como o FastAPI gera documentação automática?

Question

Accepted Answer

FastAPI **gera automaticamente documentação interativa de API** a partir do seu código — suas rotas, parâmetros e modelos Pydantic são transformados em um esquema OpenAPI, que alimenta duas UIs de docs navegáveis (Swagger UI e ReDoc) sem nenhum esforço extra.

## Você obtém docs gratuitamente

```python
class Item(BaseModel):
    name: str
    price: float = Field(gt=0, description="Price in USD")

@app.post("/items", tags=["items"], summary="Create an item")
def create_item(item: Item):
    """Create a new item with a name and price."""   # docstring → endpoint description
    return item
```

Apenas escrevendo endpoints e modelos tipados, FastAPI produz docs completos — sem necessidade de escrever ou manter um arquivo de documentação separado.

## As duas UIs de docs integradas

```text
/docs   → Swagger UI — interactive: browse endpoints AND test them in the browser
          (fill in parameters, send requests, see responses live)
/redoc  → ReDoc — a clean, readable reference-style view
/openapi.json → the raw OpenAPI schema (usable to generate client SDKs, etc.)
```

Visite `/docs` e você pode explorar cada endpoint, ver parâmetros obrigatórios e formatos de resposta, e **enviar requisições reais** diretamente do navegador — inestimável durante o desenvolvimento e para consumidores da API.

## De onde vem o conteúdo da documentação

```text
Route decorators → paths, HTTP methods, tags, summaries
Type hints       → parameter types, required/optional
Pydantic models  → request/response schemas, field constraints & descriptions
Docstrings       → endpoint descriptions
Field(..., description=, example=) → field-level docs and examples
```

Tudo é derivado do código que você já escreve — a documentação permanece automaticamente **em sincronismo** com a implementação.

## Enriquecendo a documentação

```python
app = FastAPI(title="My API", version="1.0", description="...")
@app.get("/x", response_model=Item, responses={404: {"description": "Not found"}})
```

## Por que isso importa

Documentação interativa automática é um dos recursos mais celebrados do FastAPI e uma razão importante para sua popularidade.

Porque a documentação é gerada diretamente do seu código (rotas, type hints, modelos Pydantic, docstrings), ela está sempre **em sincronismo** com a implementação real — eliminando o problema crônico de documentação ficando desatualizada, que afeta documentos escritos manualmente.

A Swagger UI interativa (`/docs`) permite que desenvolvedores e consumidores de API explorem e **testem endpoints ao vivo no navegador**, melhorando dramaticamente a experiência do desenvolvedor e reduzindo atritos de integração.

O esquema OpenAPI gerado também pode impulsionar geração de SDKs de cliente e testes de contrato.

Obter documentação de API profissional, precisa e interativa essencialmente de graça — apenas escrevendo código bem tipado — é uma vitória significativa de produtividade e qualidade, tornando isso um recurso importante e distintivo do FastAPI.