api-doc-generator
Générer une documentation OpenAPI 3.0 à partir de votre code source
Rédiger une documentation d'API à la main est lent et souvent incomplet. Cette skill génère automatiquement des spécifications OpenAPI 3.0, des exemples de requêtes et des collections Postman directement à partir de votre code, afin que votre équipe dispose toujours d'une documentation d'API exacte.
Télécharger le ZIP du skill
Importer dans Claude
Allez dans Paramètres → Capacités → Skills → Importer un skill
Activez et commencez à utiliser
Ressources lisibles par les agents
Utilisez ces liens lorsqu'un AI Agent, un crawler ou un script a besoin d'un contexte propre au lieu de lire toute la page.
Tester
Utilisation de "api-doc-generator". Route Express : GET /users/:id renvoie { id, name, email } avec le statut 200 ou 404
Résultat attendu:
YAML OpenAPI 3.0 documentant GET /users/{id} avec le schéma du paramètre de chemin, le schéma de réponse réussie incluant id (integer), name (string), email (string), et la définition de la réponse d'erreur 404
Utilisation de "api-doc-generator". Endpoint POST /orders acceptant { productId, quantity, shippingAddress } et renvoyant { orderId, status, total }
Résultat attendu:
Schéma complet du corps de requête avec les champs obligatoires, schéma de réponse avec les détails de confirmation de commande, et entrée de collection Postman prête à l'emploi avec un payload JSON d'exemple
Utilisation de "api-doc-generator". Refactorise cette documentation d'API interne en référence OpenAPI destinée au public
Résultat attendu:
Spécification OpenAPI nettoyée avec définitions de schémas de sécurité, documentation sur la limitation de débit, en-têtes de versioning et descriptions d'endpoints au format Markdown adaptées à un portail développeur public
Audit de sécurité
SûrTwo static analysis findings evaluated and dismissed as false positives. The 'weak cryptographic algorithm' alert on SKILL.md:4 is a YAML description field with no cryptography. The 'high file entropy' alert is caused by CJK/Chinese UTF-8 characters, which naturally have higher entropy than ASCII text. No actual security threats found: no network access, no filesystem operations, no external commands, no scripts, no environment variable access, and no prompt injection attempts detected.
Motifs détectés
Score de qualité
Ce que vous pouvez construire
Générer automatiquement la documentation d'API à partir du code backend
Les développeurs backend collent leurs gestionnaires de routes ou fichiers de contrôleurs et reçoivent des documents de spécification OpenAPI 3.0 complets, prêts à être utilisés par l'équipe.
Créer des collections Postman pour l'onboarding
Les développeurs frontend et les nouveaux membres de l'équipe obtiennent des collections Postman prêtes à importer avec des exemples de requêtes, afin d'explorer et de tester les API immédiatement.
Standardiser la documentation d'API entre les équipes
Les responsables d'ingénierie utilisent cette skill pour imposer une documentation OpenAPI cohérente entre les microservices, garantissant que chaque API suit le même format de spécification.
Essayez ces prompts
Génère la documentation d'API pour ce gestionnaire de route Express. Inclue la méthode HTTP, le chemin, les paramètres de requête et le format de réponse.
Crée une spécification YAML OpenAPI 3.0 complète pour ce contrôleur d'API REST. Inclue tous les endpoints, les schémas de requête, les schémas de réponse et les codes d'erreur.
Génère une collection Postman JSON à partir de cette définition d'API. Inclue les en-têtes d'autorisation, des exemples de corps de requête et des scripts de test pour chaque endpoint.
Extrais les définitions d'API de ces fichiers source écrits en Python, Java et TypeScript. Génère une spécification OpenAPI 3.0 unifiée avec une nomenclature et des exemples cohérents.
Bonnes pratiques
- Fournissez des fichiers de code source complets avec toutes les routes et tous les gestionnaires pour obtenir la documentation la plus exhaustive possible
- Relisez toujours les spécifications OpenAPI générées pour vérifier leur exactitude et ajoutez les détails de logique métier que le code seul ne peut pas exprimer
- Incluez des exemples de payloads de requête et de données de réponse attendues dans votre prompt afin de produire une documentation d'API plus riche
Éviter
- Ne collez pas de code source contenant des clés d'API, des tokens ou des secrets lorsque vous demandez la génération de documentation
- Ne publiez pas la documentation d'API générée sans avoir d'abord revu et corrigé les descriptions d'endpoints et les schémas
- Évitez de documenter des endpoints strictement internes ou obsolètes qui ne doivent pas être exposés aux consommateurs d'API externes
Foire aux questions
Quels langages de programmation cette skill prend-elle en charge ?
Cette skill génère-t-elle Swagger 2.0 ou OpenAPI 3.0 ?
Puis-je personnaliser la collection Postman générée ?
Cette skill nécessite-t-elle un accès réseau à mon API ?
En quoi est-ce différent d'outils comme Swagger UI ?
Où puis-je utiliser cette skill ?
Détails du développeur
Structure de fichiers
📄 SKILL.md