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