¿Cómo genera FastAPI documentación automática?

Question

Accepted Answer

FastAPI **genera automáticamente documentación interactiva de API** a partir de tu código — tus rutas, parámetros y modelos Pydantic se convierten en un esquema OpenAPI, que alimenta dos interfaces de documentación navegables (Swagger UI y ReDoc) sin esfuerzo adicional.

## Obtienes documentación gratis

```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
```

Simplemente escribiendo endpoints y modelos tipados, FastAPI produce documentación completa — sin necesidad de escribir o mantener un archivo de documentación separado.

## Las dos interfaces de documentación 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.)
```

Visita `/docs` y puedes explorar cada endpoint, ver parámetros requeridos y formas de respuesta, y **enviar solicitudes reales** directamente desde el navegador — invaluable durante el desarrollo y para consumidores de API.

## De dónde viene el contenido de la documentación

```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
```

Todo se deriva del código que ya escribes — la documentación se mantiene automáticamente **sincronizada** con la implementación.

## Enriqueciendo la documentación

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

## Por qué es importante

La documentación interactiva automática es una de las características más celebradas de FastAPI y una razón importante de su popularidad.

Dado que la documentación se genera directamente a partir de tu código (rutas, sugerencias de tipo, modelos Pydantic, docstrings), siempre está **sincronizada** con la implementación real — eliminando el problema crónico de documentación que se queda obsoleta, que aqueja a la documentación escrita a mano.

La interfaz Swagger UI interactiva (`/docs`) permite a los desarrolladores y consumidores de API **explorar y probar endpoints en vivo en el navegador**, mejorando dramáticamente la experiencia del desarrollador y reduciendo la fricción de integración.

El esquema OpenAPI generado también puede impulsar la generación de SDK del cliente y pruebas de contrato.

Obtener documentación de API profesional, precisa e interactiva esencialmente gratis — simplemente escribiendo código bien tipado — es una ganancia significativa de productividad y calidad, haciendo que esto sea una capacidad importante y distintiva de FastAPI.