Was macht API-Dokumentationsgenerator?
Dieser Skill generiert automatisch OpenAPI 3.0 (Swagger) Dokumentation aus API-Routendateien in deiner Codebasis.
Wann dieser Skill verwendet werden sollte
- Benutzer bittet um API-Dokumentation
- Arbeiten mit REST-API-Endpunkten
- Erstellen oder Aktualisieren von OpenAPI/Swagger-Spezifikationen
- Einrichten von API-Dokumentation für Express, FastAPI, Flask, NestJS oder ähnliche Frameworks
Anleitung
1. API-Routen entdecken
Durchsuche die Codebasis nach API-Routendefinitionen:
- Express/Node.js: Suche nach
app.get(),app.post(),router.get()usw. - FastAPI/Python: Suche nach
@app.get(),@router.post()Dekorateuren - Flask: Suche nach
@app.route()Dekorateuren - NestJS: Suche nach
@Get(),@Post(),@Controller()Dekorateuren - Rails: Suche nach Routen in
config/routes.rb
Verwende Glob, um Routendateien zu finden (z.B. **/*routes*.{js,ts,py}, **/controllers/**/*.{js,ts})
2. Routenmuster analysieren
Extrahiere für jede gefundene Route:
- HTTP-Methode: GET, POST, PUT, PATCH, DELETE
- Pfad: Die Endpunkt-URL (z.B.
/api/users/:id) - Parameter: Pfadparameter, Abfrageparameter, Request-Body
- Antwort: Erwartete Antwortstruktur
- Authentifizierung: Ob eine Authentifizierung erforderlich ist
- Beschreibung: Kommentare oder Docstrings in der Nähe der Route
3. OpenAPI-Spezifikation generieren
Erstelle oder aktualisiere eine OpenAPI 3.0 Spezifikationsdatei (üblicherweise openapi.yaml oder swagger.json):
- Beginne mit der Vorlage aus
templates/openapi-3.0.yaml - Ordne jede Route einem OpenAPI-Pfadobjekt zu
- Definiere Anfrage-/Antwort-Schemata mit JSON-Schema
- Füge Parameterdefinitionen ein (Pfad, Abfrage, Body)
- Füge Authentifizierungsschemata hinzu, falls erkannt (Bearer, API-Key, OAuth2)
- Gruppiere Endpunkte nach Tags (z.B. "Benutzer", "Produkte", "Auth")
4. Vollständigkeit überprüfen
Prüfe, ob die generierte Dokumentation Folgendes enthält:
- Alle gefundenen Endpunkte
- Korrekte HTTP-Methoden und Pfade
- Beispiele für Anfragen/Antworten, soweit möglich
- Fehlerantworten (400, 401, 404, 500 usw.)
- Sicherheitsanforderungen
5. Ausgabeort
- Speichern als
openapi.yamlim Projektstammverzeichnis, oder - Platzieren im Verzeichnis
docs/oderapi/, falls vorhanden - Benutzer nach bevorzugtem Ort fragen, falls unklar
Framework-spezifische Hinweise
Express/Node.js
- Prüfe auf Middleware, die Authentifizierung/Validierung beeinflussen könnte
- Suche nach Request-Validatoren (Joi, express-validator usw.)
- Extrahiere JSDoc-Kommentare für Endpunktbeschreibungen
FastAPI
- FastAPI generiert automatisch OpenAPI-Docs, dieser Skill kann sie jedoch verbessern
- Extrahiere Pydantic-Modelle für Anfrage-/Antwort-Schemata
- Prüfe auf Parameter wie
response_modelundstatus_code
NestJS
- Suche nach DTOs (Data Transfer Objects) für Schemata
- Prüfe auf Swagger-Dekorateure (
@ApiOperation,@ApiResponse) - Extrahiere Metadaten aus Controller- und Methodendekorateuren
Best Practices
- Vorhandene Schemata verwenden: Falls die Codebasis TypeScript-Interfaces, Pydantic-Modelle oder ähnliches enthält, verwende sie für genaue Schemata
- Beispiele einfügen: Füge Anfrage-/Antwort-Beispiele aus Tests hinzu, falls verfügbar
- Logisch gruppieren: Organisiere Endpunkte nach Ressource oder Feature-Bereich mithilfe von Tags
- Versionierung korrekt durchführen: Verwende die API-Version aus der Codebasis (z.B. "1.0.0")
- Beschreibungen hinzufügen: Verwende Code-Kommentare/Docstrings für Endpunktbeschreibungen
Unterstützende Dateien
templates/openapi-3.0.yaml: Basis-OpenAPI-Vorlageexamples.md: Framework-spezifische Beispiele