Laravel API Inspector : documentation d’API automatique (Postman, OpenAPI, HTML)

Laravel API Inspector (irabbi360/laravel-api-inspector) génère une documentation d’API à partir des routes, des FormRequest (règles de validation), des API Resources et d’annotations @LAPI*. Il produit des collections Postman, des spécifications OpenAPI 3.0 et des pages HTML. Optionnel : capture des réponses, cache, analytics. Pratique pour garder une doc à jour sans duplication manuelle.

Prérequis

• PHP 8.1+
• Laravel 10+
• MySQL 5.7+ / PostgreSQL 10+ / SQLite 3.8+

1. Installation

composer require irabbi360/laravel-api-inspector
php artisan api-inspector:install

L’installeur interactif publie la config et les migrations. Penser à lancer php artisan migrate si des tables sont ajoutées.

2. Structure de la doc

• /api-docs : documentation HTML.
• /api-docs/stats : statistiques, téléchargement Postman et OpenAPI (selon la config).
• Fichiers générés dans storage/api-docs/ (sauvegarde, exemples).

3. FormRequest → schéma de requête

Dès qu’un FormRequest est injecté dans une méthode de contrôleur, les règles de validation sont converties en schéma (types, requis, min/max, enum, etc.) :

// StoreUserRequest
public function rules() {
    return [
        'name' => 'required|string|max:255',
        'email' => 'required|email|unique:users',
        'password' => 'required|min:8|confirmed',
        'age' => 'integer|min:18|max:100',
    ];
}

La doc déduit : name (string, required, max 255), email (format email, unique), password (min 8, password_confirmation), age (integer, 18–100).

4. Annotations pour les réponses et la pagination

Schéma de réponse à partir d’une Resource :

/**
 * @LAPIresponsesSchema ProfileResource
 */
public function show(User $user) {
    return new ProfileResource($user);
}

Ou via le type de retour (détection automatique) :

public function show(User $user): ProfileResource {
    return new ProfileResource($user);
}

Pagination :

/**
 * @LAPIpagination
 */
public function index() {
    return ProfileResource::collection(User::latest()->paginate());
}

5. Paramètres de requête (query)

Format JSON :

/**
 * @LAPIQueryParams {"name":{"type":"string","required":true,"description":"Filtrer par nom"},"page":{"type":"integer","required":false},"limit":{"type":"integer","required":false}}
 */
public function index(Request $request) { ... }

Format court :

/**
 * @LAPIQueryParams name:string required, page:integer optional, limit:integer optional
 */

Ou encore :

/**
 * @LAPIQueryParams name, page, per_page, status
 */

6. Capture des réponses et cache

En config, vous pouvez activer :

• middleware_capture : enregistrement des réponses 2xx des routes API pour alimenter les exemples (Postman, OpenAPI, HTML).
• save_responses_driver : json (fichiers dans storage/api-docs/) ou cache.
• response_ttl : durée de vie du cache.

Les réponses réelles améliorent la qualité des exemples sans saisie manuelle.

7. Auth

La config permet de définir le type (ex. bearer) et l’en-tête (ex. Authorization) pour les routes protégées. Les routes considérées comme authentifiées sont documentées en conséquence.

Dépannage

Bonnes pratiques

• FormRequest partout où c’est possible pour avoir des schémas de requête complets.
• Annoter @LAPIresponsesSchema (ou typer le retour) pour les réponses structurées.
• Utiliser la capture en staging/dev pour enrichir les exemples, puis désactiver ou restreindre en prod si besoin.

Ressources

• DEV.to – Laravel API Inspector
• GitHub – irabbi360/laravel-api-inspector
• OpenAPI 3.0

Cet article s’inscrit dans notre série de guides technique et développement web. Pour un serveur ou une application sur-mesure, contact.