Configuración de Operaciones de Path¶
Hay varios parámetros que puedes pasar a tu decorador de operación de path para configurarlo.
Aviso
Ten en cuenta que estos parámetros se pasan directamente al decorador de operación de path, no a tu función de operación de path.
Código de Estado de Response¶
Puedes definir el status_code (HTTP) a usar en la response de tu operación de path.
Puedes pasar directamente el código int, como 404.
Pero si no recuerdas para qué sirve cada código numérico, puedes usar las constantes de atajo en status:
from fastapi import FastAPI, status
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post("/items/", status_code=status.HTTP_201_CREATED)
async def create_item(item: Item) -> Item:
return item
Ese código de estado será usado en la response y será añadido al esquema OpenAPI.
Detalles Técnicos
También podrías usar from starlette import status.
FastAPI proporciona el mismo starlette.status como fastapi.status solo como una comodidad para ti, el desarrollador. Pero viene directamente de Starlette.
Tags¶
Puedes añadir tags a tu operación de path, pasa el parámetro tags con una list de str (comúnmente solo un str):
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post("/items/", tags=["items"])
async def create_item(item: Item) -> Item:
return item
@app.get("/items/", tags=["items"])
async def read_items():
return [{"name": "Foo", "price": 42}]
@app.get("/users/", tags=["users"])
async def read_users():
return [{"username": "johndoe"}]
Serán añadidos al esquema OpenAPI y usados por las interfaces automáticas de documentación:
Tags con Enums¶
Si tienes una aplicación grande, podrías terminar acumulando varios tags, y querrías asegurarte de siempre usar el mismo tag para operaciones de path relacionadas.
En estos casos, podría tener sentido almacenar los tags en un Enum.
FastAPI lo soporta de la misma manera que con strings simples:
from enum import Enum
from fastapi import FastAPI
app = FastAPI()
class Tags(Enum):
items = "items"
users = "users"
@app.get("/items/", tags=[Tags.items])
async def get_items():
return ["Portal gun", "Plumbus"]
@app.get("/users/", tags=[Tags.users])
async def read_users():
return ["Rick", "Morty"]
Resumen y descripción¶
Puedes añadir un summary y una description:
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post(
"/items/",
summary="Create an item",
description="Create an item with all the information, name, description, price, tax and a set of unique tags",
)
async def create_item(item: Item) -> Item:
return item
Descripción desde docstring¶
Como las descripciones tienden a ser largas y cubrir múltiples líneas, puedes declarar la descripción de la operación de path en el docstring de la función y FastAPI lo leerá desde ahí.
Puedes escribir Markdown en el docstring, será interpretado y mostrado correctamente (teniendo en cuenta la indentación del docstring).
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post("/items/", summary="Create an item")
async def create_item(item: Item) -> Item:
"""
Create an item with all the information:
- **name**: each item must have a name
- **description**: a long description
- **price**: required
- **tax**: if the item doesn't have tax, you can omit this
- **tags**: a set of unique tag strings for this item
"""
return item
Se usará en las docs interactivas:
Descripción de la response¶
Puedes especificar la descripción de la response con el parámetro response_description:
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None
tags: set[str] = set()
@app.post(
"/items/",
summary="Create an item",
response_description="The created item",
)
async def create_item(item: Item) -> Item:
"""
Create an item with all the information:
- **name**: each item must have a name
- **description**: a long description
- **price**: required
- **tax**: if the item doesn't have tax, you can omit this
- **tags**: a set of unique tag strings for this item
"""
return item
Nota
Ten en cuenta que response_description se refiere específicamente a la response, la description se refiere a la operación de path en general.
Consejo
OpenAPI especifica que cada operación de path requiere una descripción de la response.
Así que, si no proporcionas una, FastAPI generará automáticamente una de "Successful response".
Deprecar una operación de path¶
Si necesitas marcar una operación de path como deprecada, pero sin eliminarla, pasa el parámetro deprecated:
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/", tags=["items"])
async def read_items():
return [{"name": "Foo", "price": 42}]
@app.get("/users/", tags=["users"])
async def read_users():
return [{"username": "johndoe"}]
@app.get("/elements/", tags=["items"], deprecated=True)
async def read_elements():
return [{"item_id": "Foo"}]
Se marcará claramente como deprecado en las docs interactivas:
Revisa cómo se ven las operaciones de path deprecadas y no deprecadas:
Resumen¶
Puedes configurar y añadir metadata a tus operaciones de path fácilmente pasando parámetros a los decoradores de operación de path.