Documentare OpenAPI: tags, summary și description în FastAPI

Unul dintre marile atuuri ale framework-ului FastAPI este generarea automată a documentației interactive Swagger UI (accesibilă la /docs) și ReDoc (la /redoc) conform standardului OpenAPI 3.1.

Prin parametrii din decoratorul rutei poți structura documentația profesional:

• tags: Grupează endpoint-urile în categorii logice și secțiuni vizuale pliabile.
• summary: Oferă un titlu scurt și clar afișat în lista principală a rutelor.
• description: Permite documentare amplă formatată în Markdown, incluzând tabele sau note explicative.
• deprecated=True: Marchează vizual rutele învechite ce urmează a fi eliminate în versiunile viitoare.

from fastapi import FastAPI

app = FastAPI(title="Magazin Online API", version="2.0.0")

@app.get(
    "/orders/{order_id}",
    tags=["Comenzi"],
    summary="Preluare detalii comandă",
    description="Preluare detalii comandă activă cu linii de produse, total cu TVA și stare livrare.",
    response_description="Obiectul complet al comenzii"
)
async def get_order(order_id: int):
    return {"order_id": order_id, "status": "expediat"}