Documenter une API headless avec un schéma OpenAPI généré depuis les routes REST

La documentation officielle du projet WordPress, sur developer.wordpress.org, le rappelle sans détour : « chaque route de l’API REST déclare son propre schéma, accessible via une requête OPTIONS ou directement à la racine de l’API ». Ce schéma existe déjà, pour le cœur de WordPress comme pour toute route personnalisée correctement déclarée avec un argument args détaillé. Reste à le transformer en un document OpenAPI que l’équipe front, ou une équipe partenaire externe, peut exploiter sans avoir à lire le code PHP source.

Étape 1 : récupérer le schéma brut exposé par WordPress

Une simple requête vers la racine de l’API retourne un index complet de toutes les routes déclarées, avec leurs méthodes autorisées et leurs arguments :

GET /wp-json/

{
  "routes": {
    "/wp/v2/posts": {
      "namespace": "wp/v2",
      "methods": ["GET", "POST"],
      "endpoints": [ … ]
    },
    "brasserie/v1/carte": {
      "namespace": "brasserie/v1",
      "methods": ["GET"]
    }
  }
}

Pour une route précise, une requête OPTIONS détaille le schéma complet de ses arguments, y compris les types déclarés et les valeurs possibles pour un champ enum.

Étape 2 : convertir ce schéma vers le format OpenAPI

Le format natif de WordPress ne suit pas la spécification OpenAPI (anciennement Swagger), mais la conversion reste mécanique une fois le schéma récupéré : chaque route devient un chemin (path), chaque méthode une opération, et chaque argument un paramètre ou un champ de corps de requête. Un script PHP exécuté une seule fois, ou une tâche WP-CLI personnalisée, peut automatiser cette traduction :

$serveur = rest_get_server();
$routes  = $serveur->get_routes();

foreach ( $routes as $chemin => $definitions ) {
    // Traduction de chaque route vers la structure attendue
    // par le format OpenAPI (paths, parameters, responses…)
}

Étape 3 : documenter les routes personnalisées avec autant de soin que le cœur

Le schéma généré automatiquement pour les routes du cœur de WordPress reste riche, car chaque argument y est déclaré avec un type et souvent une description. Les routes personnalisées, en revanche, héritent de ce niveau de détail uniquement si le développeur a pris soin de renseigner chaque argument dans le tableau args de register_rest_route(). Une route déclarée sans schéma d’arguments détaillé produira une documentation OpenAPI pauvre, avec des paramètres non typés et sans description.

• Vérifier que chaque route maison déclare un type pour chacun de ses paramètres.
• Ajouter une description à chaque argument, reprise telle quelle dans le document final.
• Documenter les réponses possibles, y compris les codes d’erreur renvoyés par un permission_callback qui refuse l’accès.

Étape 4 : publier le document généré à l’équipe partenaire

Une fois le fichier OpenAPI produit au format JSON ou YAML, des outils comme Swagger UI ou Redoc l’affichent sous forme de documentation interactive, consultable dans un navigateur, avec la possibilité de tester chaque route directement depuis l’interface. Cette étape transforme un schéma technique difficilement lisible en un support de travail partageable avec une équipe qui n’a jamais ouvert le code source de WordPress.

Étape 5 : maintenir la documentation à jour automatiquement

Un document généré manuellement une seule fois devient obsolète dès la première route ajoutée sans mise à jour de la documentation. Automatiser la génération, par exemple via une commande WP-CLI personnalisée exécutée à chaque déploiement, garantit que le document reflète toujours l’état réel de l’API, plutôt qu’une photographie figée au jour de sa première publication.

wp eval-file bin/generer-openapi.php --path=/var/www/monsite > docs/openapi.json

Notre verdict

Générer un schéma OpenAPI depuis les routes REST de WordPress évite de rédiger à la main une documentation qui divergerait rapidement du code réel. Le travail de fond ne réside pas dans la conversion technique, mécanique une fois écrite, mais dans la rigueur avec laquelle chaque route personnalisée déclare son propre schéma d’arguments : une route bien décrite dès sa création produit une documentation exploitable sans effort supplémentaire, une route négligée produira toujours un document incomplet, quel que soit l’outil de conversion utilisé.