Métadonnées et URL des documents¶

🌐 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.

Vous pouvez personnaliser plusieurs configurations de métadonnées dans votre application FastAPI.

Métadonnées pour l'API¶

Vous pouvez définir les champs suivants qui sont utilisés dans la spécification OpenAPI et les interfaces utilisateur de documentation automatique de l’API :

Paramètre Type Description

title str Le titre de l’API.

summary str Un court résumé de l’API. Disponible depuis OpenAPI 3.1.0, FastAPI 0.99.0.

description str Une brève description de l’API. Elle peut utiliser Markdown.

version string La version de l’API. C’est la version de votre propre application, pas d’OpenAPI. Par exemple 2.5.0.

terms_of_service str Une URL vers les Conditions d’utilisation de l’API. Le cas échéant, il doit s’agir d’une URL.

contact

dict

Les informations de contact pour l’API exposée. Cela peut contenir plusieurs champs.

champs de contact

Paramètre	Type	Description
`name`	`str`	Le nom identifiant de la personne/organisation de contact.
`url`	`str`	L’URL pointant vers les informations de contact. DOIT être au format d’une URL.
`email`	`str`	L’adresse e-mail de la personne/organisation de contact. DOIT être au format d’une adresse e-mail.

license_info

dict

Les informations de licence pour l’API exposée. Cela peut contenir plusieurs champs.

champs de license_info

Paramètre	Type	Description
`name`	`str`	OBLIGATOIRE (si un `license_info` est défini). Le nom de la licence utilisée pour l’API.
`identifier`	`str`	Une expression de licence SPDX pour l’API. Le champ `identifier` est mutuellement exclusif du champ `url`. Disponible depuis OpenAPI 3.1.0, FastAPI 0.99.0.
`url`	`str`	Une URL vers la licence utilisée pour l’API. DOIT être au format d’une URL.

Vous pouvez les définir comme suit :

Python 3.10+

from fastapi import FastAPI

description = """
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You will be able to:

* **Create users** (_not implemented_).
* **Read users** (_not implemented_).
"""

app = FastAPI(
    title="ChimichangApp",
    description=description,
    summary="Deadpool's favorite app. Nuff said.",
    version="0.0.1",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Deadpoolio the Amazing",
        "url": "http://x-force.example.com/contact/",
        "email": "dp@x-force.example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    },
)


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

Astuce

Vous pouvez écrire du Markdown dans le champ description et il sera rendu dans la sortie.

Avec cette configuration, les documents API automatiques ressembleraient à :

Identifiant de licence¶

Depuis OpenAPI 3.1.0 et FastAPI 0.99.0, vous pouvez également définir license_info avec un identifier au lieu d’une url.

Par exemple :

Python 3.10+

from fastapi import FastAPI

description = """
ChimichangApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You will be able to:

* **Create users** (_not implemented_).
* **Read users** (_not implemented_).
"""

app = FastAPI(
    title="ChimichangApp",
    description=description,
    summary="Deadpool's favorite app. Nuff said.",
    version="0.0.1",
    terms_of_service="http://example.com/terms/",
    contact={
        "name": "Deadpoolio the Amazing",
        "url": "http://x-force.example.com/contact/",
        "email": "dp@x-force.example.com",
    },
    license_info={
        "name": "Apache 2.0",
        "identifier": "Apache-2.0",
    },
)


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

Métadonnées pour les tags¶

Vous pouvez également ajouter des métadonnées supplémentaires pour les différents tags utilisés pour regrouper vos chemins d'accès avec le paramètre openapi_tags.

Il prend une liste contenant un dictionnaire pour chaque tag.

Chaque dictionnaire peut contenir :

name (requis) : un str avec le même nom de tag que vous utilisez dans le paramètre tags de vos chemins d'accès et APIRouters.
description : un str avec une courte description pour le tag. Il peut contenir du Markdown et sera affiché dans l’interface utilisateur de la documentation.
externalDocs : un dict décrivant une documentation externe avec :
- description : un str avec une courte description pour la documentation externe.
- url (requis) : un str avec l’URL de la documentation externe.

Créer des métadonnées pour les tags¶

Essayons cela avec un exemple de tags pour users et items.

Créez des métadonnées pour vos tags et transmettez-les au paramètre openapi_tags :

Python 3.10+

from fastapi import FastAPI

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://fastapi.tiangolo.com/",
        },
    },
]

app = FastAPI(openapi_tags=tags_metadata)


@app.get("/users/", tags=["users"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]


@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

Notez que vous pouvez utiliser Markdown à l’intérieur des descriptions, par exemple « login » sera affiché en gras (login) et « fancy » sera affiché en italique (fancy).

Astuce

Vous n’avez pas à ajouter des métadonnées pour tous les tags que vous utilisez.

Utiliser vos tags¶

Utilisez le paramètre tags avec vos chemins d'accès (et APIRouters) pour les affecter à différents tags :

Python 3.10+

from fastapi import FastAPI

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://fastapi.tiangolo.com/",
        },
    },
]

app = FastAPI(openapi_tags=tags_metadata)


@app.get("/users/", tags=["users"])
async def get_users():
    return [{"name": "Harry"}, {"name": "Ron"}]


@app.get("/items/", tags=["items"])
async def get_items():
    return [{"name": "wand"}, {"name": "flying broom"}]

Info

En savoir plus sur les tags dans Configuration de chemins d'accès.

Consultez les documents¶

Désormais, si vous consultez les documents, ils afficheront toutes les métadonnées supplémentaires :

Définir l’ordre des tags¶

L’ordre de chaque dictionnaire de métadonnées de tag définit également l’ordre affiché dans l’interface utilisateur de la documentation.

Par exemple, même si users viendrait après items par ordre alphabétique, il est affiché avant, car nous avons ajouté ses métadonnées comme premier dictionnaire de la liste.

URL OpenAPI¶

Par défaut, le schéma OpenAPI est servi à /openapi.json.

Mais vous pouvez le configurer avec le paramètre openapi_url.

Par exemple, pour qu’il soit servi à /api/v1/openapi.json :

Python 3.10+

from fastapi import FastAPI

app = FastAPI(openapi_url="/api/v1/openapi.json")


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

Si vous souhaitez désactiver complètement le schéma OpenAPI, vous pouvez définir openapi_url=None, cela désactivera également les interfaces utilisateur de la documentation qui l’utilisent.

URL des documents¶

Vous pouvez configurer les deux interfaces utilisateur de documentation incluses :

Swagger UI : servie à /docs.
- Vous pouvez définir son URL avec le paramètre docs_url.
- Vous pouvez la désactiver en définissant docs_url=None.
ReDoc : servie à /redoc.
- Vous pouvez définir son URL avec le paramètre redoc_url.
- Vous pouvez la désactiver en définissant redoc_url=None.

Par exemple, pour que Swagger UI soit servi à /documentation et désactiver ReDoc :

Python 3.10+

from fastapi import FastAPI

app = FastAPI(docs_url="/documentation", redoc_url=None)


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