Modèle : documentation d'API

Type d'information :Référence•"Quels sont les détails ?"

Données de référence, syntaxe exacte, paramètres et contraintes

Modèle

Ceci est un point de départ à copier et adapter, pas un exemple abouti. C’est une instance spécialisée du modèle d’article référence, adaptée à un endpoint d’API par page. Pour approfondir la relation entre documentation de référence, schémas OpenAPI et guides pas-à-pas, consultez Typologie de l’information et documentation d’API.

Utilisez une copie de ce modèle par endpoint (ou par groupe d’endpoints étroitement liés, comme GET/POST sur la même ressource). N’essayez pas de documenter une API entière sur une seule page - elle cesse d’être consultable au-delà de quelques endpoints.

---
title: "<Méthode HTTP> <chemin>"
description: "<Une phrase : ce que fait cet endpoint>"
contentType: reference
---

## Aperçu

<Une ou deux phrases : à quoi sert cet endpoint et quand l'appeler.>

## Endpoint

```
<MÉTHODE> <chemin>
```

## Authentification

<Schéma d'authentification requis, ou « Aucune » si l'endpoint est public.>

## Paramètres

| Nom | Emplacement | Type | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `<nom>` | chemin / requête / corps | `<type>` | Oui/Non | <ce qu'il fait> |

## Exemple de requête

```bash
curl -X <MÉTHODE> https://api.exemple.com/<chemin> \
  -H "Content-Type: application/json" \
  -d '{ "<champ>": "<valeur>" }'
```

## Exemple de réponse

```json
{
  "<champ>": "<valeur>"
}
```

## Codes d'erreur

| Statut HTTP | Code | Signification |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | <quand cela se produit> |
| 404 | `NOT_FOUND` | <quand cela se produit> |

## Endpoints connexes

- [<Endpoint connexe>](<lien>)

Notes de remplissage

• Chaque champ des tableaux doit provenir du contrat réel de l’API - le schéma, le code de validation, ou une requête/réponse réellement capturée. N’inventez jamais un paramètre ou un code d’erreur plausible ; c’est pire qu’une absence de documentation, car le lecteur s’y fiera.
• Gardez les exemples de requête/réponse exécutables tels quels - un lecteur doit pouvoir copier-coller la commande curl et obtenir la réponse indiquée (en masquant uniquement les vrais secrets).
• Si l’API dispose d’un contrat lisible par machine (comme une spécification OpenAPI ou un schéma JSON), générez la documentation à partir de celui-ci ou liez-le directement plutôt que de dupliquer manuellement chaque champ qu’il définit déjà - les tables manuelles et les contrats machine finiraient par diverger. Rédigez des pages de référence Markdown manuelles lorsque vous devez apporter des explications nuancées, des cas limites ou du contexte métier spécifique.