API Documenting

Omdanner route-kode til API-referencedokumentation med parametertabeller, curl-eksempler, OpenAPI-specifikationer

Af huangjia2019 · huangjia2019/claude-code-engineering

Testet · Virker ★ 8.4/10

API Documenting — Omdanner route-kode til API-referencedokumentation med parametertabeller, curl-eksempler, OpenAPI-specifikationer

Hvad det gør

Læser kildefiler for route-definitioner (Express, FastAPI, Flask, Spring, Gin) og genererer API-referencedokumentation ved hjælp af faste templates for endpoint-siderne og indekssiden, plus en valgfri OpenAPI 3.0-specifikation. Inkluderer et Python route-detektionsscript og en shell-validator for genererede specifikationer. Udløses, når brugeren beder om at dokumentere API'er, generere endpoint-dokumentation, producere en API-reference eller skrive en OpenAPI/Swagger-specifikation.

Testrapport

Klonede repoet, installerede i en throwaway HOME (rørte aldrig den rigtige ~/.claude), og bekræftede, at alle 8 filer, SKILL.md body refererer til, eksisterer — PATTERNS.md, STANDARDS.md, EXAMPLES.md, templates/{endpoint,index,openapi}, scripts/{detect_routes.py,validate_openapi.sh} — spot-hentede tre ved HTTP 200. Kørte scripts/detect_routes.py mod en 3-route Express-fil, jeg skrev; den returnerede korrekt GET /orders, POST /orders og DELETE /orders/:orderId med fil+linjenumre, så hjælperen er reel og ikke dekorativ. Opgave: dokumenter den samme orders.js. Baseline (46 linjer, 968 B) var prosa-punkter uden typer, ingen auth-sektion, ingen curl, ingen indeks; skill-kørsel (212 linjer, 3992 B) fulgte templates/index.md derefter templates/endpoint.md per route og tilføjede en base-URL/auth-header, en endpoint-oversigtstabel, en fælles response-kode-tabel, tre parametertabeller med Location/Type/Required-kolonner (0 i baseline), tre kørbare curl request/response-eksempler (0 i baseline), 401-casen, som baseline udelod, og en Notes-linje, jeg kun skrev, fordi templaten tvang sektionen — den 403 kontrolleres efter eksistens, så et gyldigt id ejet af en anden bruger returnerer 403, ikke 404. Trigger-fraser bedømt: SKULLE udløses — "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" (indlæste alle tre); SKULLE IKKE — "Design a REST API for a booking system, what endpoints should I have?" (API-design, ikke dokumentation af eksisterende kode) og "Write a README for this CLI tool" (docs, men ingen endpoints); begge korrekt afvist, 5/5. Ingen sikkerhedsbrister: ingen curl|sh, ingen base64, ingen netværkskald, ingen hemmelig adgang; validate_openapi.sh sheller kun ud til swagger-cli/npx/spectral, hvis allerede til stede. Docs fratrukket et point, fordi skillen sidder inde i et kursuslektionsprojekt uden sin egen standalone README — den omkringliggende README er undervisningsmateriale om progressiv afsløring, ikke brugsdokumentation.

Testet: 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.

Kommandoer og eksempelprompter

/api-documentingOmdanner route-kode til API-referencedokumentation med parametertabeller, curl-eksempler, OpenAPI-specifikationer

Skills udløses af almindelige forespørgsler — ingen kommandoer at huske. Efter installationen aktiverer prompter som disse skillen (på engelsk):

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

Læs hele rapporten →