API Documenting

Transforme le code de route en documentation de référence API avec tables de paramètres, exemples curl, specs OpenAPI.

par huangjia2019 · huangjia2019/claude-code-engineering

Testé · Fonctionne ★ 8.4/10

API Documenting — Transforme le code de route en documentation de référence API avec tables de paramètres, exemples curl, specs OpenAPI.

Ce que fait

Lit les fichiers source pour les définitions de route (Express, FastAPI, Flask, Spring, Gin) et génère de la documentation de référence API en utilisant des templates fixes pour les pages d'endpoint et la page d'index, plus une spécification OpenAPI 3.0 optionnelle. Inclut un script Python de détection de route et un validateur shell pour les spécifications générées. Se déclenche lorsque l'utilisateur demande de documenter des APIs, de générer de la documentation d'endpoint, de produire une référence API, ou d'écrire une spécification OpenAPI/Swagger.

Rapport de test

Cloné le dépôt, installé dans un HOME temporaire (n'a jamais touché le vrai ~/.claude), et confirmé que les 8 fichiers référencés dans le corps de SKILL.md existent — PATTERNS.md, STANDARDS.md, EXAMPLES.md, templates/{endpoint,index,openapi}, scripts/{detect_routes.py,validate_openapi.sh} — trois ont été récupérés ponctuellement en HTTP 200. Exécuté scripts/detect_routes.py sur un fichier Express à 3 routes que j'ai écrit ; il a correctement retourné GET /orders, POST /orders et DELETE /orders/:orderId avec les numéros de fichier+ligne, donc l'aide est réelle et non décorative. Tâche : documenter ce même orders.js. La référence (46 lignes, 968 B) était des puces de prose sans types, sans section d'authentification, sans curl, sans index ; l'exécution de la compétence (212 lignes, 3992 B) a suivi templates/index.md puis templates/endpoint.md par route et a ajouté un en-tête base-URL/auth, un tableau récapitulatif des endpoints, un tableau des codes de réponse courants, trois tableaux de paramètres avec les colonnes Location/Type/Required (0 dans la référence), trois exemples de requêtes/réponses curl exécutables (0 dans la référence), le cas 401 que la référence avait omis, et une ligne Notes que je n'ai écrite que parce que le template forçait la section — ce 403 est vérifié après l'existence, donc un ID valide appartenant à un autre utilisateur retourne 403 et non 404. Phrases de déclenchement jugées : DEVRAIT se déclencher — "Generate an API reference for the routes in src/api/", "Write an OpenAPI 3.0 spec for my FastAPI app", "Document all the endpoints in this Express router" (chargé les trois) ; NE DEVRAIT PAS — "Design a REST API for a booking system, what endpoints should I have?" (conception d'API, pas documentation de code existant) et "Write a README for this CLI tool" (docs mais pas d'endpoints) ; les deux ont été correctement refusées, 5/5. Pas de failles de sécurité : pas de curl|sh, pas de base64, pas d'appels réseau, pas d'accès aux secrets ; validate_openapi.sh ne fait appel à swagger-cli/npx/spectral que s'ils sont déjà présents. Docs pénalisées d'un point car la compétence se trouve dans un projet de leçon de cours sans son propre README autonome — le README environnant est du matériel pédagogique sur la divulgation progressive, pas des docs d'utilisation.

Testé le: 2026-07-21 · Claude Code 2.x (agent harness)

Installation

git clone --depth 1 https://github.com/huangjia2019/claude-code-engineering.git /tmp/api-documenting-src
mkdir -p ~/.claude/skills
cp -R /tmp/api-documenting-src/04-Skills/projects/02-progressive-skill/.claude/skills/api-documenting ~/.claude/skills/api-documenting
# No dependencies for the documentation workflow itself.
# Optional helper: python3 ~/.claude/skills/api-documenting/scripts/detect_routes.py <source_dir>  -> JSON list of routes (stdlib only, no pip installs)
# Optional helper: bash ~/.claude/skills/api-documenting/scripts/validate_openapi.sh <spec.yaml>  -> needs swagger-cli / npx / spectral, else falls back to a YAML syntax check
# The repo is a Claude Code course; this skill lives in lesson project 04-Skills/projects/02-progressive-skill. No plugin marketplace entry.

Commandes et exemples de prompts

/api-documentingTransforme le code de route en documentation de référence API avec tables de paramètres, exemples curl, specs OpenAPI.

Les skills se déclenchent sur des demandes en langage courant — aucune commande à retenir. Après installation, des prompts comme ceux-ci l'activent (en anglais) :

Generate API reference docs for this service
Create an OpenAPI spec for these endpoints
Document this API's request and response formats

Rapport complet →