Génération Swagger/OpenAPI pour PHP : Outils et bibliothèques

Génération Swagger/OpenAPI pour PHP : Aperçu complet des outils

Dans le développement web moderne, créer une documentation API de qualité est devenu non seulement une bonne pratique, mais une nécessité. Swagger (maintenant connu sous le nom d'OpenAPI) est une norme pour décrire les API RESTful, permettant d'automatiser la génération de documentation, de SDK clients et d'interfaces console de test. Dans cet article, nous examinerons en détail comment utiliser Swagger/OpenAPI pour les projets PHP, quelles bibliothèques existent et comment les intégrer correctement.

Qu'est-ce que Swagger/OpenAPI ?

L'OpenAPI Specification (OAS) est une spécification qui définit une norme pour décrire les API REST au format JSON ou YAML. Elle permet de :

• Générer automatiquement une documentation interactive (Swagger UI) ;
• Créer des bibliothèques clientes pour différents langages de programmation ;
• Vérifier la validité des requêtes et des réponses ;
• S'intégrer aux pipelines CI/CD.

Bibliothèques principales pour PHP

Pour travailler avec OpenAPI en PHP, il existe plusieurs bibliothèques populaires. Examinons chacune d'elles en détail.

1. Swagger-PHP (zircote/swagger-php)

C'est la bibliothèque la plus populaire et la plus mature pour générer une spécification OpenAPI à partir d'annotations PHP. Elle permet de décrire l'API directement dans le code, ce qui facilite le maintien de la documentation à jour.

Installation :

composer require zircote/swagger-php

Exemple d'utilisation :

<?phpuse OpenApi\\Annotations as OA;

/** * @OA\\Info( *     title="Mon API", *     version="1.0.0", *     description="Exemple d'API pour démonstration Swagger" * ) * @OA\\Server( *     url="https://api.example.com", *     description="Serveur de production" * ) */class UserController{    /**     * @OA\\Get(     *     path="/api/users",     *     summary="Obtenir la liste des utilisateurs",     *     @OA\\Response(     *         response=200,     *         description="Réponse réussie",     *         @OA\\JsonContent(type="array",     *             @OA\\Items(ref="#/components/schemas/User")     *         )     *     )     * )     */    public function getUsers()    {        // Logique de récupération des utilisateurs    }

    /**     * @OA\\Schema(     *     schema="User",     *     type="object",     *     @OA\\Property(property="id", type="integer"),     *     @OA\\Property(property="name", type="string"),     *     @OA\\Property(property="email", type="string")     * )     */    public function userSchema()    {        // Méthode vide pour décrire le schéma    }}

// Génération de la spécification$openapi = \\OpenApi\\Generator::scan(['/path/to/controllers']);file_put_contents('openapi.json', $openapi->toJson());?>

2. OpenAPI-Server (thecodingmachine/openapi-server)

Cette bibliothèque permet non seulement de décrire l'API, mais aussi de générer automatiquement le code serveur basé sur la spécification OpenAPI. Elle est particulièrement utile lors de l'utilisation du principe de développement Design-First.

Installation :

composer require thecodingmachine/openapi-server

Exemple de génération de serveur :

<?phpuse TheCodingMachine\\OpenAPI\\Server\\Builder;

// Chargement de la spécification$spec = json_decode(file_get_contents('openapi.json'), true);

// Création du serveur$builder = new Builder();$server = $builder->build($spec, 'App\\\\Controllers\\\\');

// Traitement de la requête$response = $server->handle($request);?>

3. Swagger-UI pour PHP

Pour afficher la documentation interactive, vous pouvez utiliser le Swagger UI intégré. Il existe plusieurs façons de l'intégrer :

• Utilisation d'un CDN : Connectez directement les fichiers CSS et JS de Swagger UI ;
• Installation locale :