Swagger-PHP pour PHP : guide complet avec exemples

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

Swagger-PHP est une bibliothèque puissante pour le langage PHP qui permet de générer automatiquement la spécification OpenAPI (anciennement Swagger) de votre API REST à partir d'annotations dans le code. Au lieu de rédiger manuellement d'immenses fichiers YAML ou JSON décrivant tous les endpoints, paramètres, modèles de données et réponses, il vous suffit d'ajouter des commentaires spéciaux (annotations) directement dans vos contrôleurs, modèles et routes d'application PHP. La bibliothèque analyse ces annotations et crée une spécification OpenAPI complète et valide, exportable aux formats JSON ou YAML.

Pourquoi est-ce utile ? Dans le développement web moderne, l'API est l'interface clé entre le frontend, les applications mobiles et les services tiers. Maintenir une documentation à jour est un casse-tête permanent. Swagger-PHP résout ce problème en liant directement la documentation au code source. Si vous modifiez la logique d'un endpoint, vous modifiez également l'annotation correspondante. La documentation correspond toujours au comportement réel de l'API. Cela permet d'économiser des heures de travail, de réduire les erreurs d'intégration et de rendre votre projet transparent pour les nouveaux développeurs.

De plus, la spécification OpenAPI générée peut être utilisée avec des dizaines d'outils : Swagger UI (documentation interactive permettant de tester les requêtes directement depuis le navigateur), des générateurs de SDK clients pour JavaScript, Python, Java et d'autres langages, des outils de test et de validation (comme Postman ou Insomnia), ainsi que pour la génération automatique de serveurs mock. Swagger-PHP est la norme de facto pour documenter les API PHP.

2. Installation

L'installation se fait via Composer, le gestionnaire de paquets standard pour PHP. Exécutez la commande suivante à la racine de votre projet :

composer require zircote/swagger-php

Après l'installation, le répertoire vendor/zircote/swagger-php apparaîtra dans votre projet. La bibliothèque nécessite PHP version 8.0 ou supérieure (pour prendre en charge les annotations modernes PHP 8 et les attributs). Si vous utilisez une version plus ancienne de PHP, vous aurez besoin de la version 3.x de la bibliothèque, mais il est fortement recommandé de passer à PHP 8+ et d'utiliser la dernière version de Swagger-PHP (4.x).

3. Démarrage rapide — exemple minimal fonctionnel

Créons un contrôleur très simple avec un seul endpoint et générons sa spécification OpenAPI.

Étape 1 : Créez le fichier src/Controllers/UserController.php

<?php

namespace App\Controllers;

use OpenApi\Attributes as OA;

class UserController
{
    #[OA\Get(
        path: '/api/users/{id}',
        summary: 'Obtenir un utilisateur par son ID',
        tags: ['Users']
    )]
    #[OA\Parameter(
        name: 'id',
        in: 'path',
        required: true,
        schema: new OA\Schema(type: 'integer')
    )]
    #[OA\Response(
        response: 200,
        description: 'Réponse réussie',
        content: new OA\JsonContent(
            properties: [
                new OA\Property(property: 'id', type: 'integer'),
                new OA\Property(property: 'name', type: 'string'),
                new OA\Property(property: 'email', type: 'string')
            ]
        )
    )]
    public function getUser(int $id): array
    {
        // Ici devrait se trouver la logique pour récupérer l'utilisateur depuis la BDD
        return [
            'id' => $id,
            'name' => 'Jean Dupont',
            'email' => 'jean@exemple.com'
        ];
    }
}

Étape 2 : Créez le script de génération de spécification generate-docs.php

<?php

require_once __DIR__ . '/vendor/autoload.php';

use OpenApi\Generator;

// Indiquez le répertoire contenant vos contrôleurs avec annotations
$openapi = Generator::scan(['src/Controllers']);

// Sauvegardez la spécification au format JSON
file_put_contents('openapi.json', $openapi->toJson());

echo "Spécification OpenAPI générée avec succès dans openapi.json\n";

Étape 3 : Exécutez le script

php generate-docs.php

Vous obtiendrez un fichier openapi.json contenant la spécification complète de votre API. Ouvrez-le avec Swagger UI ou un autre outil compatible pour visualiser et interagir avec votre documentation.

4. Méthodes principales et annotations avancées

Swagger-PHP prend en charge toutes les méthodes HTTP standard : GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS. Voici un exemple plus complet avec plusieurs endpoints :

<?php

namespace App\Controllers;

use OpenApi\Attributes as OA;

class ProductController
{
    #[OA\Get(
        path: '/api/products',
        summary: 'Lister tous les produits',
        tags: ['Produits']
    )]
    #[OA\Response(
        response: 200,
        description: 'Liste des produits',
        content: new OA\JsonContent(
            type: 'array',
            items: new OA\Items(ref: '#/components/schemas/Product')
        )
    )]
    public function listProducts(): array
    {
        // Logique de récupération
        return [];
    }

    #[OA\Post(
        path: '/api/products',
        summary: 'Créer un nouveau produit',
        tags: ['Produits']
    )]
    #[OA\RequestBody(
        required: true,
        content: new OA\JsonContent(ref: '#/components/schemas/ProductInput')
    )]
    #[OA\Response(
        response: 201,
        description: 'Produit créé',
        content: new OA\JsonContent(ref: '#/components/schemas/Product')
    )]
    public function createProduct(): array
    {
        // Logique de création
        return [];
    }
}

#[OA\Schema(
    schema: 'Product',
    description: 'Modèle de produit'
)]
class ProductSchema
{
    #[OA\Property(property: 'id', type: 'integer', example: 1)]
    public int $id;

    #[OA\Property(property: 'name', type: 'string', example: 'Ordinateur portable')]
    public string $name;

    #[OA\Property(property: 'price', type: 'number', format: 'float', example: 999.99)]
    public float $price;
}

#[OA\Schema(
    schema: 'ProductInput',
    description: 'Données d\'entrée pour la création d\'un produit'
)]
class ProductInputSchema
{
    #[OA\Property(property: 'name', type: 'string', example: 'Nouveau produit')]
    public string $name;

    #[OA\Property(property: 'price', type: 'number', format: 'float', example: 49.99)]
    public float $price;
}

5. Conclusion

Swagger-PHP est un outil indispensable pour tout développeur PHP souhaitant créer des API REST bien documentées et maintenables. En intégrant la documentation directement dans le code via des annotations, vous garantissez une synchronisation parfaite entre votre code et sa documentation. Que vous travailliez sur un petit projet personnel ou une application d'entreprise complexe, Swagger-PHP vous fera gagner un temps précieux et améliorera la qualité de votre travail.

N'hésitez pas à consulter la documentation officielle pour découvrir toutes les fonctionnalités avancées, comme la gestion de la sécurité (OAuth2, JWT), les schémas imbriqués, les exemples de requêtes, et bien plus encore.