fastapi/docs/fr/docs/tutorial/metadata.md

Métadonnées et URL des documents

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 :

{* ../../docs_src/metadata/tutorial001_py310.py hl[3:16, 19:32] *}

/// tip | 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 :

{* ../../docs_src/metadata/tutorial001_1_py310.py hl[31] *}

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 :

{* ../../docs_src/metadata/tutorial004_py310.py hl[3:16,18] *}

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

/// tip | 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 :

{* ../../docs_src/metadata/tutorial004_py310.py hl[21,26] *}

/// info

En savoir plus sur les tags dans Configuration de chemins d'accès{.internal-link target=_blank}.

///

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 :

{* ../../docs_src/metadata/tutorial002_py310.py hl[3] *}

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 :

{* ../../docs_src/metadata/tutorial003_py310.py hl[3] *}