Étendre OpenAPI¶

🌐 Traduction par IA et humains

Cette traduction a été réalisée par une IA guidée par des humains. 🤝

Elle peut contenir des erreurs d'interprétation du sens original, ou paraître peu naturelle, etc. 🤖

Vous pouvez améliorer cette traduction en nous aidant à mieux guider le LLM d'IA.

Version anglaise

Il existe des cas où vous pouvez avoir besoin de modifier le schéma OpenAPI généré.

Dans cette section, vous verrez comment faire.

Le processus normal¶

Le processus normal (par défaut) est le suivant.

Une application (instance) FastAPI a une méthode .openapi() censée retourner le schéma OpenAPI.

Lors de la création de l'objet application, un chemin d'accès pour /openapi.json (ou pour l'URL que vous avez définie dans votre openapi_url) est enregistré.

Il renvoie simplement une réponse JSON avec le résultat de la méthode .openapi() de l'application.

Par défaut, la méthode .openapi() vérifie la propriété .openapi_schema pour voir si elle contient des données et les renvoie.

Sinon, elle les génère à l'aide de la fonction utilitaire fastapi.openapi.utils.get_openapi.

Et cette fonction get_openapi() reçoit comme paramètres :

title : Le titre OpenAPI, affiché dans les documents.
version : La version de votre API, p. ex. 2.5.0.
openapi_version : La version de la spécification OpenAPI utilisée. Par défaut, la plus récente : 3.1.0.
summary : Un court résumé de l'API.
description : La description de votre API ; elle peut inclure du markdown et sera affichée dans la documentation.
routes : Une liste de routes ; chacune correspond à un chemin d'accès enregistré. Elles sont extraites de app.routes.

Info

Le paramètre summary est disponible à partir d'OpenAPI 3.1.0, pris en charge par FastAPI 0.99.0 et versions ultérieures.

Remplacer les valeurs par défaut¶

En vous appuyant sur les informations ci-dessus, vous pouvez utiliser la même fonction utilitaire pour générer le schéma OpenAPI et remplacer chaque partie dont vous avez besoin.

Par exemple, ajoutons l’extension OpenAPI de ReDoc pour inclure un logo personnalisé.

FastAPI normal¶

Tout d’abord, écrivez votre application FastAPI comme d’habitude :

Python 3.10+

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

Générer le schéma OpenAPI¶

Ensuite, utilisez la même fonction utilitaire pour générer le schéma OpenAPI, dans une fonction custom_openapi() :

Python 3.10+

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

Modifier le schéma OpenAPI¶

Vous pouvez maintenant ajouter l’extension ReDoc, en ajoutant un x-logo personnalisé à l’« objet » info dans le schéma OpenAPI :

Python 3.10+

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

Mettre en cache le schéma OpenAPI¶

Vous pouvez utiliser la propriété .openapi_schema comme « cache » pour stocker votre schéma généré.

Ainsi, votre application n’aura pas à générer le schéma à chaque fois qu’un utilisateur ouvre les documents de votre API.

Il ne sera généré qu’une seule fois, puis le même schéma en cache sera utilisé pour les requêtes suivantes.

Python 3.10+

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

Remplacer la méthode¶

Vous pouvez maintenant remplacer la méthode .openapi() par votre nouvelle fonction.

Python 3.10+

from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()


@app.get("/items/")
async def read_items():
    return [{"name": "Foo"}]


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="Custom title",
        version="2.5.0",
        summary="This is a very custom OpenAPI schema",
        description="Here's a longer description of the custom **OpenAPI** schema",
        routes=app.routes,
    )
    openapi_schema["info"]["x-logo"] = {
        "url": "https://fastapi.tiangolo.com/img/logo-margin/logo-teal.png"
    }
    app.openapi_schema = openapi_schema
    return app.openapi_schema


app.openapi = custom_openapi

Vérifier¶

Une fois que vous allez sur http://127.0.0.1:8000/redoc, vous verrez que vous utilisez votre logo personnalisé (dans cet exemple, le logo de FastAPI) :