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

Génération Swagger/OpenAPI pour PHP : automatisation de la documentation d'API

\n\n

Swagger (maintenant OpenAPI) est un standard de description d'API RESTful qui permet aux développeurs, clients et outils automatisés de comprendre les capacités d'un service sans accès au code source. Pour les développeurs PHP, l'outil clé est la bibliothèque zircote/swagger-php (anciennement connue sous le nom de swagger-php), qui génère automatiquement une spécification OpenAPI à partir d'annotations dans le code.

\n\n

Qu'est-ce que zircote/swagger-php ?

\n\n

C'est la bibliothèque principale pour la génération de spécifications OpenAPI en PHP. Elle analyse les annotations PHPDoc dans les contrôleurs, modèles et routes, créant un fichier JSON/YAML qui peut être utilisé pour :

\n\n

\n
• La génération automatique de documentation (Swagger UI, ReDoc)
\n
• La génération de bibliothèques clientes pour différents langages
\n
• Le test d'API (Postman, Insomnia)
\n
• La validation des requêtes et réponses
\n

\n\n

Installation et configuration

\n\n

Installation via Composer :

\n\n

composer require zircote/swagger-php

\n\n

La configuration minimale pour Laravel (ou tout framework) inclut la création d'annotations dans le contrôleur. Exemple d'un contrôleur simple avec annotations OpenAPI :

\n\n

<?php\n\nnamespace App\\Http\\Controllers\\Api;\n\nuse OpenApi\\Annotations as OA;\n\n/**\n * @OA\\Info(title="My API", version="1.0.0")\n * @OA\\Server(url="https://api.example.com")\n */\nclass UserController extends Controller\n{\n    /**\n     * @OA\\Get(\n     *     path="/api/users/{id}",\n     *     summary="Obtenir un utilisateur par ID",\n     *     @OA\\Parameter(\n     *         name="id",\n     *         in="path",\n     *         required=true,\n     *         @OA\\Schema(type="integer")\n     *     ),\n     *     @OA\\Response(\n     *         response=200,\n     *         description="Réponse réussie",\n     *         @OA\\JsonContent(ref="#/components/schemas/User")\n     *     ),\n     *     @OA\\Response(response=404, description="Utilisateur non trouvé")\n     * )\n     */\n    public function show($id)\n    {\n        // logique\n    }\n}

\n\n

Génération de la spécification

\n\n

Pour créer le fichier OpenAPI, exécutez la commande :

\n\n

vendor/bin/openapi src -o public/openapi.yaml

\n\n

Ou utilisez le code PHP :

\n\n

<?php\n\nuse OpenApi\\Generator;\n\n$openapi = Generator::scan(['/path/to/project/src']);\nfile_put_contents('public/openapi.json', $openapi->toJson());

\n\n

Fonctionnalités avancées

\n\n

La bibliothèque prend en charge :

\n\n

\n
• Schémas imbriqués — création automatique de modèles à partir d'annotations
\n
• Regroupement d'endpoints via @OA\\Tag
\n
• Sécurité — @OA\\SecurityScheme pour JWT, OAuth2
\n
• Exemples de requêtes — @OA\\RequestBody avec exemples
\n

\n\n

Exemple de modèle avec annotations :

\n\n

<?php\n\n/**\n * @OA\\Schema(\n *     schema="User",\n *     required={"id", "email"},\n *     @OA\\Property(property="id", type="integer", format="int64"),\n *     @OA\\Property(property="email", type="string", format="email"),\n *     @OA\\Property(property="name", type="string"),\n *     @OA\\Property(property="created_at", type="string", format="date-time")\n * )\n */\nclass User\n{\n    // propriétés\n}

\n\n

Intégration avec les frameworks

\n\n

Pour Laravel, il existe le paquet darkaonline/l5-swagger qui ajoute :

\n\n

\n
• Génération automatique à chaque requête
\n
• Swagger UI intégré
\n
• Configuration via fichier config
\n

\n\n

Installation :

\n\n

composer require darkaonline/l5-swagger\nphp artisan vendor:publish --provider="L5Swagger\\L5SwaggerServiceProvider"

\n\n

Pour Symfony, utilisez nelmio/api-doc-bundle.

\n\n

Comparaison