API Platform génère nativement une documentation riche et interactive. Cependant, pour des besoins d'automatisation (CI/CD), de génération de clients ou d'import dans des outils comme Postman, il est indispensable de savoir exporter cette spécification de manière statique.

La commande essentielle : api:swagger:export

Depuis les versions récentes d'API Platform, la commande a évolué pour se concentrer sur le standard OpenAPI. Elle permet de dumper instantanément l'intégralité de vos ressources, types de données et endpoints.

Syntaxe et usage standard

Pour exporter votre documentation au format JSON à la racine de votre projet :

bin/console api:swagger:export --output=openapi.json

Options avancées de personnalisation

• --yaml : Par défaut, l'export est en JSON. Utilisez cette option pour obtenir un fichier YAML, souvent plus lisible pour les humains.
  bin/console api:swagger:export --yaml --output=openapi.yaml
• --spec-version : Permet de forcer une version spécifique (2.0, 3.0.0, 3.1.0). Très utile pour la compatibilité avec d'anciens générateurs de code SDK.
• --format : Permet de spécifier le format de normalisation si vous avez des besoins spécifiques de sérialisation.

Pourquoi automatiser cet export ?

L'exportation statique offre des avantages majeurs pour la productivité de l'équipe :

• Contract Testing : Validez que les changements dans votre code Symfony n'altèrent pas le contrat d'interface attendu par le Front-end.
• Client Generation : Utilisez des outils comme OpenAPI Generator pour créer automatiquement vos SDK TypeScript, Swift ou Go à partir du fichier exporté.
• Documentation Portal : Alimentez des portails externes comme Redoc ou Stoplight pour offrir une documentation publique hors de votre application de production.

En intégrant bin/console api:swagger:export dans vos scripts de déploiement, vous garantissez que votre documentation de référence est toujours synchronisée avec votre code de production.