Revue Risque faible Intermédiaire ≈ 1 h 30 gagnées

Documenter une API technique

Produit la documentation de référence d'une API (fiches endpoints, conventions, guide de démarrage) à partir du code ou d'une collection.

Télécharger le skill (.zip) Guide d'installation

Objectif

Rédige la documentation technique d'une API à partir de son code, d'une collection de requêtes ou d'une liste d'endpoints : fiches de référence par endpoint (méthode, chemin, paramètres typés, codes de retour, exemples fictifs), conventions d'authentification et d'erreurs, guide de démarrage, avec déductions et éléments non vérifiables explicitement marqués. À déclencher pour documenter une API REST, produire une référence d'endpoints, rédiger un guide développeur ou formaliser un contrat d'interface.

Entrées acceptées

Ce que vous obtenez

Limites et supervision humaine

Ce skill peut fonctionner de façon autonome sur des tâches à faible enjeu. Une relecture reste recommandée en contexte sensible.

Niveau de risque déclaré : faible. Le skill n'exécute que la tâche décrite dans son SKILL.md ; elle n'invente ni fait, ni chiffre, ni citation et signale les champs qu'elle ne peut pas renseigner.

Aperçu du SKILL.md

Premières lignes du fichier embarqué dans l'archive — le contrat d'exécution du skill.

---
name: documenter-api-technique
description: Rédige la documentation technique d'une API à partir de son code, d'une collection de requêtes ou d'une liste d'endpoints : fiches de référence par endpoint (méthode, chemin, paramètres typés, codes de retour, exemples fictifs), conventions d'authentification et d'erreurs, guide de démarrage, avec déductions et éléments non vérifiables explicitement marqués. À déclencher pour documenter une API REST, produire une référence d'endpoints, rédiger un guide développeur ou formaliser un contrat d'interface.
---

# Documenter une API technique

## Mission

Rédiger la documentation technique d'une API à partir de ses éléments fournis (code, collection de requêtes, description) : référence des endpoints, conventions d'authentification et d'erreurs, guide de démarrage.

## Résultat attendu

Un document Markdown comprenant :
- la vue d'ensemble : finalité de l'API, URL de base, versionnage, conventions communes ;
- la référence des endpoints, une fiche par endpoint suivant `templates/fiche-endpoint.md` : méthode et chemin, description, paramètres (chemin, requête, corps) typés et obligatoires, codes de retour, exemple de requête et de réponse ;
- les conventions d'authentification et d'autorisation ;
- la convention des erreurs (format, codes, signification) ;
- le guide de démarrage : obtenir un accès, premier appel, erreurs fréquentes.

Précision attendue : chaque endpoint documenté provient des entrées ; tout détail non vérifiable dans les entrées (ex. comportement d'erreur réel) est marqué `[À CONFIRMER]` ; les exemples sont cohérents avec les types documentés.

## Situations d'usage

- « Documente cette API à partir du code. »
- « Rédige la référence des endpoints de ce service. »
- « Produit le guide développeur de notre API REST. »
- Fichiers fournis : code source des routes ou contrôleurs, collection (Postman, Insomnia), spécification existante à compléter, description textuelle (txt, md, json, html).

## Ce que le skill ne fait pas

- Génération d'une spécification OpenAPI/Swagger formelle (fichier YAML/JSON conforme) : le skill produit une documentation rédigée, pas un contrat machine.
- Conception ou refonte de l'API (choix des ressources, versionnage).
- Tests d'appels réels contre l'API (aucune requête n'est émise).
- Documentation des SDK clients ou du code métier interne.
- Rédaction marketing du portail développeur.

## Entrées obligatoires

- **Source de vérité sur l'API** : au moins une forme exploitable — code des routes/contrôleurs, collection de requêtes exportée, ou liste d'endpoints avec méthodes et paramètres.

Installation

Téléchargez le fichier et, si vous le souhaitez, vérifiez qu'il est authentique (shasum -a 256 documenter-api-technique.zip).
Décompressez-le : vous obtenez un dossier contenant SKILL.md et ses ressources.
Importez le dossier dans claude.ai, Claude Code ou via l'API.