Documenter comme un pro avec laravel scribe

Documenter vos API est crucial pour clarifier le fonctionnement des endpoints, améliorer la communication en équipe et faciliter l'intégration des développeurs tiers. Avec Scribe, créer une documentation API complète et interactive à partir de votre code Laravel devient un jeu d'enfant. Comparé à Swagger, Scribe se démarque par sa simplicité d'intégration et sa facilité d'utilisation, offrant une clarté incomparable à vos équipes et utilisateurs.

⚙️ Avantages de Scribe :

✅ Documentation Automatique : Générez instantanément une documentation détaillée de vos API, réduisant ainsi le temps de création et de maintenance manuelle.

✅ Intégration Facile : Intégrez Scribe à votre projet Laravel en toute simplicité grâce à une configuration claire et des conventions simples.

✅ Personnalisable : Personnalisez la documentation générée par Scribe selon vos besoins en modifiant les titres, le logo, descriptions et exemples des endpoints.

Installation de laravel Scribe dans un projet laravel

composer require --dev knuckleswtf/scribe

Publication de la configuration de scribe

php artisan vendor:publish --tag=scribe-config

NB : Après la publication du fichier de configuration vous aurai dans config/scribe.php Vous pouvez customiser le titre de votre documentation, ajouter une description et le logo de votre application. Vous pouvez meme changer le thème de la page de docuementation par default.

Let's go pour un cas pratique :

/**
  * @group Gestion des residences
 *
 * Activation d'une residence
 *
 * Cette action permettra de réafficher la residence sur l'application
 * @authenticated
 */
public function enable(Residence $residence, EnableResidenceAction $enableResidenceAction)
{
    $this->authorize('enable', $residence);
 
    $residence = $enableResidenceAction->handle($residence);
 
    return $this->responseSuccess(__('Residence activée avec succès'), new ResidenceResource($residence));
}

On utilise avec laravel Scribe des annotations afin de documenter les fonctions de nos classes. Une fois terminer vous devez exécuter la commande suivant afin de générer la documentation a documentation :

php artisan scribe:generate

Vous pouvez retrouver plus d' exemple et best pratique sur la documentation Installation de laravel Scribe dans un projet laravel

composer require --dev knuckleswtf/scribe

Publication de la configuration de scribe

php artisan vendor:publish --tag=scribe-config

NB : Après la publication du fichier de configuration vous aurai dans config/scribe.php Vous pouvez customiser le titre de votre documentation, ajouter une description et le logo de votre application. Vous pouvez meme changer le thème de la page de docuementation par default.

Let's go pour un cas pratique :

/**
  * @group Gestion des residences
 *
 * Activation d'une residence
 *
 * Cette action permettra de réafficher la residence sur l'application
 * @authenticated
 */
public function enable(Residence $residence, EnableResidenceAction $enableResidenceAction)
{
    $this->authorize('enable', $residence);
 
    $residence = $enableResidenceAction->handle($residence);
 
    return $this->responseSuccess(__('Residence activée avec succès'), new ResidenceResource($residence));
}

On utilise avec laravel Scribe des annotations afin de documenter les fonctions de nos classes. Une fois terminer vous devez exécuter la commande suivant afin de générer la documentation a documentation :

php artisan scribe:generate

Vous pouvez retrouver plus d' exemple et best pratique sur la documentation : https://scribe.knuckles.wtf/laravel/