Génération de Documentation d'API

La documentation d'API réduit les frictions entre les équipes front-end et back-end. Les développeurs backend définissent les points d'accès (endpoints) et fournissent une description claire des méthodes de requête et des formats de réponse, permettant ainsi aux équipes frontend d'intégrer les services efficacement.

Approches pour Documenter les APIs

Plusieurs méthodes existent pour produire de la documentation d'API :

• Rédaction manuelle avec des outils comme Microsoft Word ou des fichiers Markdown.
• Utilisation de plateformes commerciales dédiées (souvent payantes).
• Déploiement d'outils open source au sein de l'entreprise, tels que Yapi.
• Génération automatique lorsque l'API est construite avec Django REST Framework, grâce à des bibliothèques comme Swagger ou CoreAPI.

Production Automatique avec REST Framework

Django REST Framework peut générer automatiquement une documentation interactive sous forme de page web. Cette fonctionnalité s'applique aux vues héritant d'APIView ou de ses sous-classes.

Configuration de CoreAPI

La génération de documentation requiert la bibliothèque coreapi. Procédez à son installation :

pip install coreapi

Intégration du Point d'Accès à la Documentation

Ajoutez une route dédiée dans votre configuration d'URL principale pour servir la documentation. La vue correspondante est fournie par REST Framework.

from rest_framework.documentation import include_docs_urls

urlpatterns = [
    path('api-docs/', include_docs_urls(title='Documentation Technique des Services')),
]

Ajout de Descriptions aux Points d'Accès

Les descriptions sont spécifiées via les docstrings des classes de vue.

Pour une vue avec une seule méthode :

class ProduitListView(generics.ListAPIView):
    """
    Récupère l'ensemble du catalogue de produits.
    """
    queryset = Produit.objects.all()

Pour une vue combinant plusieurs méthodes (ex: Liste et Création) :

class CatalogueView(generics.ListCreateAPIView):
    """
    get:
    Retourne la liste paginée de tous les articles disponibles.

    post:
    Soumet un nouvel article au catalogue.
    """

Pour un ViewSet (ensemble de vues), utiliser les noms d'actions :

class StockViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
    """
    list:
    Affiche les niveaux de stock actuels pour chaque produit.

    retrieve:
    Expose les détails de stock pour un produit spécifique (identifié par son ID).

    seuil:
    Signale les produits dont le stock est inférieur au seuil de réapprovisionnement.

    actualiser:
    Met à jour la quantité en stock pour un produit donné.
    """

Accès à l'Interface de Documentation

Une fois le serveur lancé, naviguez vers http://127.0.0.1:8000/api-docs/ pour visualiser la documentation générée. En cas d'erreur indiquant un attribut manquant (get_link), ajoutez cette configuration dans vos paramètres :

# Dans settings.py
REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'rest_framework.schemas.coreapi.AutoSchema',
}

Notes Supplémentaires

1. L'action retrieve d'un ViewSet apparaît sous le nom read dans l'interface de documentation.
2. Pour afficher une description (Description) pour un paramètre dans la documentation, définissez l'attribut help_text sur le champ correspondant dans votre modèle ou votre sérialiseur.

Exemple au niveau du modèle :

class Adherent(models.Model):
    # ...
    date_inscription = models.DateField(auto_now_add=True, help_text="Date de souscription au service")
    # ...

Exemple au niveau du sérialiseur :

class AdherentSerializer(serializers.ModelSerializer):
    class Meta:
        model = Adherent
        fields = ['id', 'nom', 'date_inscription']
        extra_kwargs = {
            'nom': {'help_text': 'Nom complet de l\'adhérent'}
        }