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

> Étapes pour produire une documentation exploitable par une autre équipe à partir du schéma déjà déclaré par les routes REST de WordPress.

- Auteur : Clément Hadrot
- Publié le : 2026-02-10
- Mis à jour le : 2026-02-10
- Catégorie : Headless & API
- URL : https://wpmoderne.dev.wordpress-developpement.fr/headless/documenter-api-headless-openapi-routes-rest/

## L’essentiel

- WordPress expose déjà un schéma via /wp-json
- Une conversion suffit vers un format OpenAPI
- Documenter les routes maison, pas seulement le cœur

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…)
}
```

> L'essentiel à retenir : WordPress expose déjà un schéma via /wp-json ; Une conversion suffit vers un format OpenAPI ; Documenter les routes maison, pas seulement le cœur

## É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é.