Guide complet Swagger-PHP pour PHP : tutoriel et exemples

Qu'est-ce que Swagger-PHP et pourquoi l'utiliser ?

Swagger-PHP est une puissante bibliothèque PHP qui génère automatiquement la documentation de vos API REST au format OpenAPI (anciennement Swagger). Au lieu de rédiger manuellement des fichiers YAML ou JSON, vous décrivez votre API directement dans le code grâce aux annotations PHPDoc. La bibliothèque analyse ces annotations et produit une spécification OpenAPI complète, visualisable avec Swagger UI, ReDoc ou d'autres outils.

Pourquoi l'utiliser ?

• Automatisation : La documentation est toujours synchronisée avec le code. Vous modifiez un endpoint, vous mettez à jour l'annotation, et la documentation est prête.
• Standardisation : OpenAPI est le standard industriel pour décrire les API REST, supporté par des centaines d'outils.
• Confort pour le frontend : Les développeurs d'applications clientes peuvent importer la spécification dans Postman, Insomnia ou générer du code client.
• Tests : La spécification peut être utilisée pour tester automatiquement votre API.
• Documentation interactive : Swagger UI permet de tester les endpoints directement depuis le navigateur.

Installation de Swagger-PHP

L'installation se fait via Composer, le gestionnaire de paquets standard pour PHP. Ouvrez un terminal dans le dossier racine de votre projet et exécutez :

composer require zircote/swagger-php

Que vous utilisiez Laravel, Symfony ou un autre framework, l'installation reste la même. Une fois installé, le dossier vendor/zircote/swagger-php apparaît dans votre projet.

Optionnel : Pour visualiser la documentation, vous aurez besoin de Swagger UI. Vous pouvez l'installer via npm :

npm install swagger-ui-dist

Ou simplement télécharger la version précompilée depuis le site officiel de Swagger.

Démarrage rapide avec un exemple de code

Créons une API simple pour gérer une liste de tâches (Todo List) et générons sa documentation.

Étape 1 : Créez un fichier index.php avec votre API :

<?php
/**
 * @OA\Info(
 *     title="Todo API",
 *     version="1.0.0",
 *     description="API simple pour gérer des tâches"
 * )
 * @OA\Server(
 *     url="http://localhost:8000",
 *     description="Serveur local"
 * )
 */

use OpenApi\Annotations as OA;

/**
 * @OA\Get(
 *     path="/tasks",
 *     summary="Récupérer la liste de toutes les tâches",
 *     @OA\Response(
 *         response=200,
 *         description="Réponse réussie",
 *         @OA\JsonContent(
 *             type="array",
 *             @OA\Items(ref="#/components/schemas/Task")
 *         )
 *     )
 * )
 */
function getTasks() {
    $tasks = [
        ['id' => 1, 'title' => 'Acheter du lait', 'completed' => false],
        ['id' => 2, 'title' => 'Écrire un article', 'completed' => true]
    ];
    header('Content-Type: application/json');
    echo json_encode($tasks);
}

/**
 * @OA\Post(
 *     path="/tasks",
 *     summary="Créer une nouvelle tâche",
 *     @OA\RequestBody(
 *         required=true,
 *         @OA\JsonContent(ref="#/components/schemas/TaskInput")
 *     ),
 *     @OA\Response(
 *         response=201,
 *         description="Tâche créée",
 *         @OA\JsonContent(ref="#/components/schemas/Task")
 *     )
 * )
 */
function createTask() {
    // Logique de création de tâche
    echo json_encode(['id' => 3, 'title' => 'Nouvelle tâche', 'completed' => false]);
}

/**
 * @OA\Schema(
 *     schema="Task",
 *     @OA\Property(property="id", type="integer"),
 *     @OA\Property(property="title", type="string"),
 *     @OA\Property(property="completed", type="boolean")
 * )
 * @OA\Schema(
 *     schema="TaskInput",
 *     @OA\Property(property="title", type="string"),
 *     @OA\Property(property="completed", type="boolean")
 * )
 */

// Routage simple
$uri = $_SERVER['REQUEST_URI'];
$method = $_SERVER['REQ