Documentation interactive de l'API FastAPI

FastAPI génère automatiquement une documentation interactive de l'API à partir des annotations de type dans le code, fournissant deux interfaces par défaut : Swagger UI et ReDoc. Les développeurs peuvent tester les API directement dans la documentation sans aucun outil supplémentaire.


Accéder à la documentation de l'API

Après avoir exécuté l'application FastAPI, visitez l'adresse suivante pour consulter la documentation :

AdresseType de documentFonctionnalités
http://127.0.0.1:8000/docsSwagger UITest interactif : cliquez sur "Try it out" pour envoyer des requêtes.
http://127.0.0.1:8000/redocReDocBonne expérience de lecture, adaptée pour parcourir et consulter les définitions d'API.
http://127.0.0.1:8000/openapi.jsonOpenAPI JSONSpécification OpenAPI brute au format JSON, disponible pour être utilisée par des outils.

Swagger UI

Swagger UI fournit une interface utilisateur intuitive pour tester les API directement dans le navigateur :

Étapes pour tester l'API

  1. Cliquez sur la route que vous souhaitez tester pour en afficher les détails
  2. Cliquez sur le bouton"Essayer"Button
  3. Saisissez les valeurs des paramètres
  4. Cliquer sur le bouton"Exécuter"envoie la requête
  5. Affichez les résultats de la réponse


ReDoc

ReDoc se concentre sur la lisibilité des documents, adapté à la consultation des définitions d'API :


Spécification OpenAPI

Utilisation de FastAPIOpenAPILa norme convertit les API en « schémas ». Visitezhttp://127.0.0.1:8000/openapi.jsonVous pouvez consulter le JSON OpenAPI brut :

{
    "openapi": "3.1.0",
    "info": {
        "title": "FastAPI",
        "version": "0.1.0"
    },
    "paths": {
        "/items/{item_id}": {
            "get": {
                "responses": {
                    "200": {
                        "description": "Successful Response"
                    }
                }
            }
        }
    }
}

Objectif de la spécification OpenAPI :

  • Alimente les systèmes de documentation Swagger UI et ReDoc
  • Générer automatiquement du code client dans divers langages
  • Intégration avec des outils de test d'API (comme Postman)
  • Compatible avec un grand nombre d'outils et de plateformes tiers

Personnaliser les informations de documentation de l'API

Lors de la création d'une instance FastAPI, vous pouvez personnaliser les métadonnées de la documentation :

Exemple

from fastapi import FastAPI

app = FastAPI(
    title="Mon API",                    # Titre de l'API
    description="Ceci est un exemple d'API, démontrant les fonctionnalités de personnalisation de la documentation",  # Description de l'API
    version="1.0.0",                    # Version de l'API
    terms_of_service="http://example.com/terms/",  # URL des conditions d'utilisation
    contact={                           # Informations de contact
        "name": "Développeur",
        "url": "http://example.com/contact/",
        "email": "dev@example.com",
    },
    license_info={                      # Informations sur la licence
        "name": "MIT",
        "url": "https://opensource.org/licenses/MIT",
    },
)

Ajouter des informations de documentation pour les routes

Vous pouvez ajouter des informations de documentation détaillées pour chaque route dans les décorateurs et les fonctions :

Exemple

from typing import Annotated
from fastapi import FastAPI, Path, Query

app = FastAPI()


@app.get(
    "/items/{item_id}",
    summary="Obtenir les informations du produit",              # Bref résumé
    description="Obtenir des informations détaillées sur le produit à partir de l'ID du produit",  # Description détaillée
    response_description=Objet d'informations produit,   # Description de la réponse
    tags=["Gestion des produits"],                   # Étiquettes de groupe
)
async def read_item(
    item_id: Annotated[int, Path(ge=1, description="ID du produit")],
    q: Annotated[str | None, Query(description=“Mots-clés de recherche”)] = Aucune,
):
    """
Obtenir les informations sur le produit :

- **item_id**: L'identifiant unique du produit.
- **q**: mot-clé de recherche facultatif
    """

    return {"item_id": item_id, "q": q}

Description du paramètre de documentation :

ParamètrePositionDescription
summarydécorateurBref résumé de la route, affiché dans la liste des routes.
descriptiondécorateurDescription détaillée de la route, prend en charge Markdown.
response_descriptiondécorateurDescription de la réponse
tagsdécorateurRegroupement des routes, affiché par catégories de tags dans la documentation.
chaîne de documentationcorps de fonctionLes docstrings de fonction s'affichent comme descriptions.

Si les deux sont définis simultanémentdescriptionet la docstring de la fonction,descriptionPrend le pas. Les docstrings prennent en charge le format Markdown, adapté pour rédiger des explications plus longues.


Regrouper à l'aide de tags

tagsLes paramètres peuvent regrouper des routes associées pour un affichage plus clair dans la documentation :

Exemple

from fastapi import FastAPI

app = FastAPI()


@app.get("/users/", tags=["Gestion des utilisateurs"])
async def read_users():
    return [{"username": "Rick"}, {"username": "Morty"}]


@app.get("/items/", tags=["Gestion des produits"])
async def read_items():
    return [{"name": "Foo"}, {"name": "Bar"}]

Dans Swagger UI, les routes sont affichées groupées par tag.


Désactiver la documentation

Dans les environnements de production, vous pouvez souhaiter désactiver la documentation automatique :

Exemple

from fastapi import FastAPI

# Désactiver la documentation
app = FastAPI(docs_url=None, redoc_url=None)

Résumé

  • FastAPI génère automatiquement deux types de documentation interactive : Swagger UI et ReDoc
  • Le contenu de la documentation est automatiquement généré en fonction des annotations de type dans le code, et la documentation se synchronise automatiquement lorsque le code est mis à jour
  • Utilisationtitle、description、tagsPersonnalisez les informations de documentation avec des paramètres tels que ceux-ci :
  • Les docstrings des fonctions apparaissent également dans la documentation.
  • L'environnement de production est accessible viadocs_url=NoneDésactiver la documentation
autres extensions