Configuración avanzada de las operaciones de path¶
OpenAPI operationId¶
Advertencia
Si no eres una persona "experta" en OpenAPI, probablemente no necesitas leer esto.
Puedes asignar el operationId de OpenAPI para ser usado en tu operación de path con el parámetro operation_id.
En este caso tendrías que asegurarte de que sea único para cada operación.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/", operation_id="some_specific_id_you_define")
async def read_items():
return [{"item_id": "Foo"}]
Usando el nombre de la función de la operación de path en el operationId¶
Si quieres usar tus nombres de funciones de API como operationIds, puedes iterar sobre todos ellos y sobrescribir operation_id de cada operación de path usando su APIRoute.name.
Deberías hacerlo después de adicionar todas tus operaciones de path.
from fastapi import FastAPI
from fastapi.routing import APIRoute
app = FastAPI()
@app.get("/items/")
async def read_items():
return [{"item_id": "Foo"}]
def use_route_names_as_operation_ids(app: FastAPI) -> None:
"""
Simplify operation IDs so that generated API clients have simpler function
names.
Should be called only after all routes have been added.
"""
for route in app.routes:
if isinstance(route, APIRoute):
route.operation_id = route.name # in this case, 'read_items'
use_route_names_as_operation_ids(app)
Consejo
Si llamas manualmente a app.openapi(), debes actualizar el operationIds antes de hacerlo.
Advertencia
Si haces esto, debes asegurarte de que cada una de tus funciones de las operaciones de path tenga un nombre único.
Incluso si están en diferentes módulos (archivos Python).
Excluir de OpenAPI¶
Para excluir una operación de path del esquema OpenAPI generado (y por tanto del la documentación generada automáticamente), usa el parámetro include_in_schema y asigna el valor como False;
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/", include_in_schema=False)
async def read_items():
return [{"item_id": "Foo"}]
Descripción avanzada desde el docstring¶
Puedes limitar las líneas usadas desde el docstring de una operación de path para OpenAPI.
Agregar un \f (un carácter de "form feed" escapado) hace que FastAPI trunque el output utilizada para OpenAPI en ese punto.
No será mostrado en la documentación, pero otras herramientas (como Sphinx) serán capaces de usar el resto.
from typing import Set, Union
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()
class Item(BaseModel):
name: str
description: Union[str, None] = None
price: float
tax: Union[float, None] = None
tags: Set[str] = set()
@app.post("/items/", response_model=Item, summary="Create an item")
async def create_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
\f
:param item: User input.
"""
return item