API Documenting

Gjør rute-kode om til API-referansedokumentasjon med parametertabeller, curl-eksempler, OpenAPI-spesifikasjoner

av huangjia2019 · huangjia2019/claude-code-engineering

Bestått ★ 8.4/10

API Documenting — Gjør rute-kode om til API-referansedokumentasjon med parametertabeller, curl-eksempler, OpenAPI-spesifikasjoner

Hva den gjør

Leser kildefiler for rutedefinisjoner (Express, FastAPI, Flask, Spring, Gin) og genererer API-referansedokumentasjon ved hjelp av faste maler for endepunktsidene og indekssiden, pluss en valgfri OpenAPI 3.0-spesifikasjon. Inkluderer et Python rute-deteksjonsskript og en shell-validator for genererte spesifikasjoner. Utløses når brukeren ber om å dokumentere APIer, generere endepunktsdokumentasjon, produsere en API-referanse, eller skrive en OpenAPI/Swagger-spesifikasjon.

Testrapport

Klonet repoet, installerte i en midlertidig HOME (rørte aldri den virkelige ~/.claude), og bekreftet at alle 8 filene SKILL.md-kroppen refererer til eksisterer — PATTERNS.md, STANDARDS.md, EXAMPLES.md, templates/{endpoint,index,openapi}, scripts/{detect_routes.py,validate_openapi.sh} — spot-hentet tre med HTTP 200. Kjørte scripts/detect_routes.py mot en 3-ruters Express-fil jeg skrev; den returnerte korrekt GET /orders, POST /orders og DELETE /orders/:orderId med fil+linjenumre, så hjelperen er ekte og ikke dekorativ. Oppgave: dokumenter den samme orders.js. Baseline (46 linjer, 968 B) var prosa-punkter uten typer, ingen auth-seksjon, ingen curl, ingen indeks; ferdighetskjøring (212 linjer, 3992 B) fulgte templates/index.md deretter templates/endpoint.md per rute og la til en base-URL/auth-header, en endepunkt-sammendragstabell, en felles respons-kode-tabell, tre parametertabeller med Location/Type/Required-kolonner (0 i baseline), tre kjørbare curl-forespørsel/respons-eksempler (0 i baseline), 401-tilfellet baseline utelot, og en Notes-linje jeg bare skrev fordi malen tvang frem seksjonen — at 403 sjekkes etter eksistens, så en gyldig ID eid av en annen bruker returnerer 403 ikke 404. Utløserfraser vurdert: SKULLE utlø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" (lastet alle tre); SKULLE IKKE — "Design a REST API for a booking system, what endpoints should I have?" (API-design, ikke dokumentering av eksisterende kode) og "Write a README for this CLI tool" (dokumentasjon, men ingen endepunkter); begge korrekt avvist, 5/5. Ingen sikkerhetsfeil: ingen curl|sh, ingen base64, ingen nettverkskall, ingen hemmelig tilgang; validate_openapi.sh kaller bare swagger-cli/npx/spectral hvis allerede til stede. Dokumentasjon redusert ett poeng fordi ferdigheten ligger inne i et kursleksjonsprosjekt uten egen frittstående README — den omkringliggende README er undervisningsmateriell om progressiv avsløring, ikke bruksdokumentasjon.

Testet på: 2026-07-21 · Claude Code 2.x (agent harness)

Installer

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-documentingGjør rute-kode om til API-referansedokumentasjon med parametertabeller, curl-eksempler, OpenAPI-spesifikasjoner

Skills utløses av vanlige forespørsler — ingen kommandoer å huske. Etter installasjonen 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

Full rapport →